# CKEditor 5

<a id="ckeditor5/latest/examples/builds-custom/collaborative-document-editor.html">source file: "ckeditor5/latest/examples/builds-custom/collaborative-document-editor.html"</a>

## Collaborative document editor

CKEditor 5 is a highly flexible framework that was created with collaboration in mind. It lets you build your custom editor of any type, with any set of [features](#ckeditor5/latest/features/index.html) and the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) type that you need where multiple authors can easily work on the same rich text documents. This feature-rich editor also brings many edition- and management-enhancing tools to the table, turning it into a full-fledged editing experience comparable with the most popular solutions such as Google Docs or Microsoft Word.

By default, CKEditor 5 filters out any content that is unsupported by its plugins and configuration. Check out the [General HTML Support (“GHS”)](#ckeditor5/latest/features/html/general-html-support.html) feature that allows you to enable HTML features that are not explicitly supported by any other dedicated CKEditor 5 plugins.

<a id="ckeditor5/latest/examples/builds-custom/full-featured-editor.html">source file: "ckeditor5/latest/examples/builds-custom/full-featured-editor.html"</a>

## Feature-rich editor

CKEditor 5 is a highly flexible framework that lets you build your custom editor of any type (like [classic](#ckeditor5/latest/examples/builds/classic-editor.html), [inline](#ckeditor5/latest/examples/builds/inline-editor.html), [distraction-free](#ckeditor5/latest/examples/builds/balloon-block-editor.html), or [document-like](#ckeditor5/latest/examples/builds/document-editor.html)), with any set of [features](#ckeditor5/latest/features/index.html) and the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) type that you need [in no time](https://ckeditor.com/ckeditor-5/builder/?redirect=docs).

This custom editor preset contains almost all non-collaborative CKEditor 5 features. You can use it to create your own content or to paste some existing content from Microsoft Word, Google Docs, text documents, or any online resources.

This editor was configured specifically to allow testing as many features as possible in one demo, with a multiline toolbar (with some features grouped into dropdowns) that gives you easy access to all available features. It is based on the classic editor, providing you with a boxed editing area with a toolbar, placed in a specific position on the page. The toolbar has been specially configured to host as many features as possible in a convenient setup. CKEditor 5 offers a dedicated [accessibility help dialog](#ckeditor5/latest/features/accessibility.html--displaying-keyboard-shortcuts-in-the-editor) that displays a list of all available keyboard shortcuts in a dialog. It can be opened by pressing Alt \+ 0 (on Windows) or Option \+ 0 (on macOS) or via toolbar.

Thanks to the [autoformatting](#ckeditor5/latest/features/autoformat.html) feature you can also use Markdown-like inline shortcodes as you type to create and format your content without using the toolbar buttons. The [slash command](#ckeditor5/latest/features/slash-commands.html) feature lets you format and insert content on the go.

You can also see the [collaborative document editor](#ckeditor5/latest/examples/builds-custom/collaborative-document-editor.html), to try out features such as comments, comments archive, track changes, or revision history, and other features enhancing document editing functions.

By default, CKEditor 5 filters out any content that is unsupported by its plugins and configuration. Check out the [General HTML Support (“GHS”)](#ckeditor5/latest/features/html/general-html-support.html) feature that allows you to enable HTML features that are not explicitly supported by any other dedicated CKEditor 5 plugins.

While this demo has the [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature enabled, please consider that the comments and track changes features are not enabled and hence these elements will not show up in the content. Read more about handling such situations in the import from Word’s [features comparison](#ckeditor5/latest/features/converters/import-word/features-comparison.html--collaboration-features) guide. You can test these features working together in the [official import from Word demo](https://ckeditor.com/import-from-word/demo/).

<a id="ckeditor5/latest/examples/builds/balloon-block-editor.html">source file: "ckeditor5/latest/examples/builds/balloon-block-editor.html"</a>

## Balloon block editor

The balloon block editor type lets you create your content directly in its target location with the help of two toolbars:

* A balloon toolbar that appears next to the selected editable document element (offering inline content formatting tools).
* A [block toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar) accessible using the toolbar handle button  attached to the editable content area and following the selection in the document (bringing additional block formatting tools). The  button is also a handle that can be used to drag and drop blocks around the content.

<a id="ckeditor5/latest/examples/builds/balloon-editor.html">source file: "ckeditor5/latest/examples/builds/balloon-editor.html"</a>

## Balloon editor

The balloon editor type lets you create your content directly in its target location with the help of a balloon toolbar that appears next to the selected editable document element.

<a id="ckeditor5/latest/examples/builds/classic-editor.html">source file: "ckeditor5/latest/examples/builds/classic-editor.html"</a>

## Classic editor

The classic editor type shows a boxed editing area with a toolbar, placed in a specific position on the page.

<a id="ckeditor5/latest/examples/builds/document-editor.html">source file: "ckeditor5/latest/examples/builds/document-editor.html"</a>

## Document editor

The editor in this example is a feature–rich preset focused on rich text editing experience similar to the native word processors. It works best for creating documents which are usually later printed or exported to PDF files.

See the [tutorial](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html) to learn how to create this kind of an editor (and similar) with a custom UI layout on top of [DecoupledEditor](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html).

<a id="ckeditor5/latest/examples/builds/inline-editor.html">source file: "ckeditor5/latest/examples/builds/inline-editor.html"</a>

## Inline editor

The inline editor type lets you create your content directly in its target location with the help of a floating toolbar that appears when the editable text is focused.

In this example the [image styles](#ckeditor5/latest/features/images/images-styles.html) configuration was changed to enable left- and right-aligned images.

<a id="ckeditor5/latest/examples/builds/multi-root-editor.html">source file: "ckeditor5/latest/examples/builds/multi-root-editor.html"</a>

## Multi-root editor

The multi-root editor type is an editor type that features multiple, separate editable areas.

The main difference between using a multi-root editor and using multiple separate editors (like in the [inline editor demo](#ckeditor5/latest/examples/builds/inline-editor.html)) is the fact that in a multi-root editor all editable areas belong to the same editor instance share the same configuration, toolbar and the undo stack, and produce one document.

<a id="ckeditor5/latest/examples/builds/multi-root-editor.html--editor-example-configuration">

### Editor example configuration

Check out the [Editor types](#ckeditor5/latest/getting-started/setup/editor-types.html--multi-root-editor) guide to learn more about implementing this kind of editor. You will find implementation steps there. You can see this example editor’s code below.

View editor configuration script 

```
import {
    MultiRootEditor,
    Essentials,
    Bold,
    Italic,
    Heading,
    Link,
    Table,
    MediaEmbed,
    List,
    Indent
} from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

MultiRootEditor
    .create( {
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials,
            Heading,
            Bold,
            Italic,
            Link,
            Table,
            MediaEmbed,
            List,
            Indent
        ],
        toolbar: {
            items: [
                'undo', 'redo',
                '|', 'heading',
                '|', 'bold', 'italic',
                '|', 'link', 'insertTable', 'mediaEmbed',
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'
            ]
        },
        roots: {
            header: {
                element: document.querySelector( '#header' ),
            },
            content: {
                element: document.querySelector( '#content' ),
            },
            leftSide: {
                element: document.querySelector( '#left-side' ),
            },
            rightSide: {
                element: document.querySelector( '#right-side' )
            }
        }
    } )
    .then( editor => {
        window.editor = editor;

        // Append toolbar to a proper container.
        const toolbarContainer = document.querySelector( '#toolbar' );
        toolbarContainer.appendChild( editor.ui.view.toolbar.element );

        // Make toolbar sticky when the editor is focused.
        editor.ui.focusTracker.on( 'change:isFocused', () => {
            if ( editor.ui.focusTracker.isFocused ) {
                toolbarContainer.classList.add( 'sticky' );
            } else {
                toolbarContainer.classList.remove( 'sticky' );
            }
        } );
    } )
    .catch( error => {
        console.error( 'There was a problem initializing the editor.', error );
    } );

```

View editor content listing 

```
<div id="toolbar"></div>
<!--
    Wrapping the structure inside a pair of
    contenteditable="true" + contenteditable="false" elements
    is required to provide proper caret handling when
    using arrow keys at the start and end of an editable area.

    You can skip them if you don't want to move the
    caret between editable areas using arrow keys.
!-->
<div contenteditable="true">
    <div contenteditable="false">
        <div class="editor">
            <div id="header">
                Header content is inserted here.
            </div>
        </div>
        <div class="editor">
            <div id="content">
                Main content is inserted here.
            </div>
        </div>
        <div class="boxes">
            <div class="box box-left editor">
                <div id="left-side">
                    Left-side box content is inserted here.
                </div>
            </div>
            <div class="box box-right editor">
                <div id="right-side">
                    Right-side box content is inserted here.
                </div>
            </div>
        </div>
    </div>
</div>

<style>
    .editor {
        border: #ccced1 1px solid;
        margin-top: 10px;
    }

    .boxes {
        margin-top: 10px;
        display: flex;
    }

    .box {
        margin-top: 0px;
        width: 50%;
    }

    /*
        Make the editable "fill" the whole box.
        The box will grow if the other box grows too.
        This makes the whole box "clickable".
    */
    .box .ck-editor__editable {
        height: 100%;
    }

    .box-left {
        margin-right: 10px;
    }

    /*
        When toolbar receives this class, it becomes sticky.
        If the toolbar would be scrolled outside of the visible area,
        instead it is kept at the top edge of the window.
    */
    #toolbar.sticky {
        position: sticky;
        top: 0px;
        z-index: 10;
    }
</style>

```

<a id="ckeditor5/latest/examples/builds/multi-root-editor.html--setting-and-reading-editor-data">

### Setting and reading editor data

Please note that setting and reading the editor data is different for multi-root editor.

Pass an object when setting the editor data 

Setting the data using `editor.setData()`:

```
    editor.setData( {
        header: '<p>Content for header part.</p>',
        content: '<p>Content for main part.</p>',
        leftSide: '<p>Content for left-side box.</p>',
        rightSide: '<p>Content for right-side box.</p>'
    } );

```

Setting the data through `config.roots.<root name>.initialData`:

```
    MultiRootEditor.create(
        {
            roots: {
                header: {
                    initialData: '<p>Content for header part.</p>',
                    element: document.querySelector( '#header' )
                },
                content: {
                    initialData: '<p>Content for main part.</p>',
                    element: document.querySelector( '#content' )
                },
                leftSide: {
                    initialData: '<p>Content for left-side box.</p>',
                    element: document.querySelector( '#left-side' )
                },
                rightSide: {
                    initialData: '<p>Content for right-side box.</p>',
                    element: document.querySelector( '#right-side' )
                }
            }
        }
    );

```

Specify root name when obtaining the data 

```
    editor.getData( { rootName: 'leftSide' } ); // -> '<p>Content for left-side box.</p>'

```

Learn more about using the multi-root editor in its [API documentation](../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html).

<a id="ckeditor5/latest/examples/framework/bottom-toolbar-editor.html">source file: "ckeditor5/latest/examples/framework/bottom-toolbar-editor.html"</a>

## Editor with a bottom toolbar and button grouping

The following custom editor example showcases an editor instance with the main toolbar displayed at the bottom of the editing window. To make it possible, this example uses the [DecoupledEditor](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) with the [main toolbar](../../api/module%5Feditor-decoupled%5Fdecouplededitoruiview-DecoupledEditorUIView.html#member-toolbar) injected after the editing root into the DOM. Learn more about the [decoupled UI in CKEditor 5](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html) to find out the details of this process.

Additionally, thanks to the flexibility offered by the [CKEditor 5 UI framework](#ckeditor5/latest/framework/architecture/ui-library.html), the main toolbar has been uncluttered by moving buttons related to text formatting into the custom “Formatting options” dropdown. All remaining dropdown and (button) tooltips have been tuned to open upward for the best user experience. Similar effect can also be achieved by using the [built-in toolbar grouping option](#ckeditor5/latest/getting-started/setup/toolbar.html--grouping-toolbar-items-in-dropdowns-nested-toolbars).

The presented combination of the UI and editor’s features works best for integrations where text creation comes first and formatting is applied occasionally. Some examples are email applications, (forum) post editors, chats, or instant messaging. You can probably recognize this UI setup from popular applications such as Gmail, Slack, or Zendesk.

<a id="ckeditor5/latest/examples/framework/bottom-toolbar-editor.html--editor-example-configuration">

### Editor example configuration

View editor configuration script 

```

import {
    DecoupledEditor,
    Plugin,
    Alignment,
    Autoformat,
    Bold,
    Italic,
    Strikethrough,
    Subscript,
    Superscript,
    Underline,
    BlockQuote,
    clickOutsideHandler,
    Essentials,
    Font,
    Heading,
    HorizontalLine,
    Image,
    ImageCaption,
    ImageResize,
    ImageStyle,
    ImageToolbar,
    ImageUpload,
    Indent,
    Link,
    List,
    MediaEmbed,
    Paragraph,
    RemoveFormat,
    Table,
    TableToolbar,
    DropdownButtonView,
    DropdownPanelView,
    DropdownView,
    ToolbarView,
    IconFontColor,
    registerIcon
} from 'ckeditor5';

const fontColorIcon =/* #__PURE__ */ registerIcon( 'fontColor', IconFontColor );

class FormattingOptions extends Plugin {
    /**
    * @inheritDoc
    */
    static get pluginName() {
        return 'FormattingOptions';
    }

    /**
    * @inheritDoc
    */
    constructor( editor ) {
        super( editor );

        editor.ui.componentFactory.add( 'formattingOptions', locale => {
            const t = locale.t;
            const buttonView = new DropdownButtonView( locale );
            const panelView = new DropdownPanelView( locale );
            const dropdownView = new DropdownView( locale, buttonView, panelView );
            const toolbarView = this.toolbarView = dropdownView.toolbarView = new ToolbarView( locale );

            // Accessibility: Give the toolbar a human-readable ARIA label.
            toolbarView.set( {
                ariaLabel: t( 'Formatting options toolbar' )
            } );

            // Accessibility: Give the dropdown a human-readable ARIA label.
            dropdownView.set( {
                label: t( 'Formatting options' )
            } );

            // Toolbars in dropdowns need specific styling, hence the class.
            dropdownView.extendTemplate( {
                attributes: {
                    class: [ 'ck-toolbar-dropdown' ]
                }
            } );

            // Accessibility: If the dropdown panel is already open, the arrow down key should focus the first child of the #panelView.
            dropdownView.keystrokes.set( 'arrowdown', ( data, cancel ) => {
                if ( dropdownView.isOpen ) {
                    toolbarView.focus();
                    cancel();
                }
            } );

            // Accessibility: If the dropdown panel is already open, the arrow up key should focus the last child of the #panelView.
            dropdownView.keystrokes.set( 'arrowup', ( data, cancel ) => {
                if ( dropdownView.isOpen ) {
                    toolbarView.focusLast();
                    cancel();
                }
            } );

            // The formatting options should not close when the user clicked:
            // * the dropdown or it contents,
            // * any editing root,
            // * any floating UI in the "body" collection
            // It should close, for instance, when another (main) toolbar button was pressed, though.
            dropdownView.on( 'render', () => {
                clickOutsideHandler( {
                    emitter: dropdownView,
                    activator: () => dropdownView.isOpen,
                    callback: () => { dropdownView.isOpen = false; },
                    contextElements: [
                        dropdownView.element,
                        ...[ ...editor.ui.getEditableElementsNames() ].map( name => editor.ui.getEditableElement( name ) ),
                        document.querySelector( '.ck-body-wrapper' )
                    ]
                } );
            } );

            // The main button of the dropdown should be bound to the state of the dropdown.
            buttonView.bind( 'isOn' ).to( dropdownView, 'isOpen' );
            buttonView.bind( 'isEnabled' ).to( dropdownView );

            // Using the font color icon to visually represent the formatting.
            buttonView.set( {
                tooltip: t( 'Formatting options' ),
                icon: fontColorIcon()
            } );

            dropdownView.panelView.children.add( toolbarView );

            toolbarView.fillFromConfig(
                editor.config.get( 'formattingOptions' ),
                editor.ui.componentFactory
            );

            return dropdownView;
        } );
    }
}

DecoupledEditor
    .create( {
        root: {
            element: document.querySelector( '#editor-content' ),
        },
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Alignment,
            Autoformat,
            BlockQuote,
            Bold,
            Essentials,
            Font,
            Heading,
            HorizontalLine,
            Image,
            ImageCaption,
            ImageResize,
            ImageStyle,
            ImageToolbar,
            ImageUpload,
            Indent,
            Italic,
            Link,
            List,
            MediaEmbed,
            Paragraph,
            RemoveFormat,
            Strikethrough,
            Subscript,
            Superscript,
            Table,
            TableToolbar,
            Underline,
            FormattingOptions
        ],
        toolbar: [
            'undo',
            'redo',
            '|',
            'formattingOptions',
            '|',
            'link',
            'blockQuote',
            'uploadImage',
            'insertTable',
            'mediaEmbed',
            'horizontalLine',
            '|',
            {
                label: 'Lists',
                icon: false,
                items: [ 'bulletedList', 'numberedList', '|', 'outdent', 'indent' ]
            }
        ],
        // Configuration of the formatting dropdown.
        formattingOptions: [
            'undo',
            'redo',
            '|',
            'fontFamily',
            'fontSize',
            'fontColor',
            'fontBackgroundColor',
            '|',
            'bold',
            'italic',
            'underline',
            'strikethrough',
            '|',
            'alignment',
            '|',
            'bulletedList',
            'numberedList',
            '|',
            'outdent',
            'indent',
            '|',
            'removeFormat'
        ],

        image: {
            resizeUnit: 'px',
            toolbar: [
                'imageStyle:inline',
                'imageStyle:wrapText',
                'imageStyle:breakText',
                '|',
                'toggleImageCaption',
                'imageTextAlternative'
            ]
        },

        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        }
    } )
    .then( editor => {
        window.editor = editor;

        const toolbarContainer = document.querySelector( '#editor-toolbar-container' );

        toolbarContainer.appendChild( editor.ui.view.toolbar.element );

        overrideDropdownPositionsToNorth( editor, editor.ui.view.toolbar );
        overrideDropdownPositionsToNorth( editor, editor.plugins.get( 'FormattingOptions' ).toolbarView );

        overrideTooltipPositions( editor.ui.view.toolbar );
        overrideTooltipPositions( editor.plugins.get( 'FormattingOptions' ).toolbarView );
    } )
    .catch( err => {
        console.error( err.stack );
    } );

/**
 * Force all toolbar dropdown panels to use northern positions rather than southern (editor default).
 * This will position them correctly relative to the toolbar at the bottom of the editing root.
 *
 * @private
 * @param {module:core/editor/editor~Editor} editor
 * @param {module:ui/toolbar/toolbarview~ToolbarView} toolbarView
 */
function overrideDropdownPositionsToNorth( editor, toolbarView ) {
    const {
        south, north, southEast, southWest, northEast, northWest,
        southMiddleEast, southMiddleWest, northMiddleEast, northMiddleWest
    } = DropdownView.defaultPanelPositions;

    let panelPositions;

    if ( editor.locale.uiLanguageDirection !== 'rtl' ) {
        panelPositions = [
            northEast, northWest, northMiddleEast, northMiddleWest, north,
            southEast, southWest, southMiddleEast, southMiddleWest, south
        ];
    } else {
        panelPositions = [
            northWest, northEast, northMiddleWest, northMiddleEast, north,
            southWest, southEast, southMiddleWest, southMiddleEast, south
        ];
    }

    for ( const item of toolbarView.items ) {
        if ( !( item instanceof DropdownView ) ) {
            continue;
        }

        item.on( 'change:isOpen', () => {
            if ( !item.isOpen ) {
                return;
            }

            item.panelView.position = DropdownView._getOptimalPosition( {
                element: item.panelView.element,
                target: item.buttonView.element,
                fitInViewport: true,
                positions: panelPositions
            } ).name;
        } );
    }
}

/**
 * Forces all toolbar items to display tooltips to the north.
 * This will position them correctly relative to the toolbar at the bottom of the editing root.
 *
 * @param {module:ui/toolbar/toolbarview~ToolbarView} toolbarView
 */
function overrideTooltipPositions( toolbarView ) {
    for ( const item of toolbarView.items ) {
        if ( item.buttonView ) {
            item.buttonView.tooltipPosition = 'n';
        } else if ( item.tooltipPosition ) {
            item.tooltipPosition = 'n';
        }
    }
}


```

View editor content listing 

```
<style>
    #editor {
        display: flex;
        flex-direction: column;
    }

    #editor-content {
        border-bottom-left-radius: 0;
        border-bottom-right-radius: 0;
    }

    #editor-content:not(.ck-focused) {
        border-color: var(--ck-color-base-border);
    }

    #editor-toolbar-container > .ck.ck-toolbar {
        border-top-width: 0;
        border-top-left-radius: 0;
        border-top-right-radius: 0;
    }

    .ck.ck-content {
        font-family: Helvetica, Arial, sans-serif;
        padding: 3em 2em 2em;
    }

    .ck.ck-content h2 {
        border: 0;
        font-size: 1.3em;
        padding-top: 0.2em;
        padding-bottom: 0.2em;
        margin-bottom: 0.4em;
    }

    .ck.ck-content .ck-horizontal-line.ck-widget {
        text-align: center;
    }

    .ck.ck-content .ck-horizontal-line.ck-widget hr {
        margin: 5px auto;
        width: 50px;
        height: 1px;
        display: inline-block;
    }
</style>

<div id="editor">
    <div id="editor-content">
            Editor content is inserted here.
    </div>
    <div id="editor-toolbar-container"></div>
</div>


```

<a id="ckeditor5/latest/examples/framework/chat-with-mentions.html">source file: "ckeditor5/latest/examples/framework/chat-with-mentions.html"</a>

## Chat with mentions

The [mention](#ckeditor5/latest/features/mentions.html) feature allows developing rich–text applications (like chats) with autocomplete suggestions displayed in a dedicated panel as the user types a pre-configured marker. For instance, in the editor below, type **“@”** to mention users and **“#”** to select from the list of available tags.

Learn how to [configure mention feeds](#ckeditor5/latest/features/mentions.html--configuration) in the dedicated guide and check out the full source code of this example below if you want to implement your own chat using CKEditor 5 WYSIWYG editor.

<a id="ckeditor5/latest/examples/framework/chat-with-mentions.html--editor-example-configuration">

### Editor example configuration

The following code will let you run the editor inside a chat application like in the example above.

View editor configuration script 

```
import {
    ClassicEditor,
    Bold,
    Italic,
    Strikethrough,
    Underline,
    Essentials,
    Link,
    Mention,
    Paragraph
} from 'ckeditor5';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '.chat__editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        extraPlugins: [ Essentials, Paragraph, Mention, MentionLinks, Bold, Italic, Underline, Strikethrough, Link ],
        toolbar: {
            items: [
                'undo', 'redo',
                '|',
                'heading',
                '|',
                'bold', 'italic', 'underline', 'strikethrough',
                '|',
                'link', 'uploadImage', 'insertTable', 'mediaEmbed',
                '|',
                'bulletedList', 'numberedList', 'outdent', 'indent'
            ]
        },
        mention: {
            feeds: [
                {
                    marker: '@',
                    feed: [
                        { id: '@cflores', avatar: 'm_1', name: 'Charles Flores' },
                        { id: '@gjackson', avatar: 'm_2', name: 'Gerald Jackson' },
                        { id: '@wreed', avatar: 'm_3', name: 'Wayne Reed' },
                        { id: '@lgarcia', avatar: 'm_4', name: 'Louis Garcia' },
                        { id: '@rwilson', avatar: 'm_5', name: 'Roy Wilson' },
                        { id: '@mnelson', avatar: 'm_6', name: 'Matthew Nelson' },
                        { id: '@rwilliams', avatar: 'm_7', name: 'Randy Williams' },
                        { id: '@ajohnson', avatar: 'm_8', name: 'Albert Johnson' },
                        { id: '@sroberts', avatar: 'm_9', name: 'Steve Roberts' },
                        { id: '@kevans', avatar: 'm_10', name: 'Kevin Evans' },
                        { id: '@mwilson', avatar: 'w_1', name: 'Mildred Wilson' },
                        { id: '@mnelson', avatar: 'w_2', name: 'Melissa Nelson' },
                        { id: '@kallen', avatar: 'w_3', name: 'Kathleen Allen' },
                        { id: '@myoung', avatar: 'w_4', name: 'Mary Young' },
                        { id: '@arogers', avatar: 'w_5', name: 'Ashley Rogers' },
                        { id: '@dgriffin', avatar: 'w_6', name: 'Debra Griffin' },
                        { id: '@dwilliams', avatar: 'w_7', name: 'Denise Williams' },
                        { id: '@ajames', avatar: 'w_8', name: 'Amy James' },
                        { id: '@randerson', avatar: 'w_9', name: 'Ruby Anderson' },
                        { id: '@wlee', avatar: 'w_10', name: 'Wanda Lee' }
                    ],
                    itemRenderer: customItemRenderer
                },
                {
                    marker: '#',
                    feed: [
                        '#american', '#asian', '#baking', '#breakfast', '#cake', '#caribbean',
                        '#chinese', '#chocolate', '#cooking', '#dairy', '#delicious', '#delish',
                        '#dessert', '#desserts', '#dinner', '#eat', '#eating', '#eggs', '#fish',
                        '#food', '#foodgasm', '#foodie', '#foodporn', '#foods', '#french', '#fresh',
                        '#fusion', '#glutenfree', '#greek', '#grilling', '#halal', '#homemade',
                        '#hot', '#hungry', '#icecream', '#indian', '#italian', '#japanese', '#keto',
                        '#korean', '#lactosefree', '#lunch', '#meat', '#mediterranean', '#mexican',
                        '#moroccan', '#nom', '#nomnom', '#paleo', '#poultry', '#snack', '#spanish',
                        '#sugarfree', '#sweet', '#sweettooth', '#tasty', '#thai', '#vegan',
                        '#vegetarian', '#vietnamese', '#yum', '#yummy'
                    ]
                }
            ]
        }
    } )
    .then( editor => {
        const editingView = editor.editing.view;
        const rootElement = editingView.document.getRoot();

        window.editor = editor;

        // Clone the first message in the chat when "Send" is clicked, fill it with new data
        // and append to the chat list.
        document.querySelector( '.chat-send' ).addEventListener( 'click', () => {
            const message = editor.getData();

            if ( !message ) {
                editingView.change( writer => {
                    writer.addClass( 'highlighted', rootElement );
                    editingView.focus();
                } );

                setTimeout( () => {
                    editingView.change( writer => {
                        writer.removeClass( 'highlighted', rootElement );
                    } );
                }, 650 );

                return;
            }

            const clone = document.querySelector( '.chat__posts li' ).cloneNode( true );

            clone.classList.add( 'new-post' );
            clone.querySelector( 'img' ).src = 'https://ckeditor.com/docs/ckeditor5/latest/assets/img/m_0.jpg';
            clone.querySelector( 'strong' ).textContent = 'CKEditor User';

            const mailtoUser = clone.querySelector( '.chat__posts__post__mailto-user' );

            mailtoUser.textContent = '@ckeditor';
            mailtoUser.href = 'mailto:info@cksource.com';

            clone.querySelector( '.chat__posts__post__time' ).textContent = 'just now';
            clone.querySelector( '.chat__posts__post__content' ).innerHTML = message;

            document.querySelector( '.chat__posts' ).appendChild( clone );

            editor.setData( '' );
            editingView.focus();
        } );
    } )
    .catch( err => {
        console.error( err.stack );
    } );

/*
 * This plugin customizes the way mentions are handled in the editor model and data.
 * Instead of a classic <span class="mention"></span>,
 */
function MentionLinks( editor ) {
    // The upcast converter will convert a view
    //
    //		<a href="..." class="mention" data-mention="...">...</a>
    //
    // element to the model "mention" text attribute.
    editor.conversion.for( 'upcast' ).elementToAttribute( {
        view: {
            name: 'a',
            key: 'data-mention',
            classes: 'mention',
            attributes: {
                href: true
            }
        },
        model: {
            key: 'mention',
            value: viewItem => editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem )
        },
        converterPriority: 'high'
    } );

    // Downcast the model "mention" text attribute to a view
    //
    //		<a href="..." class="mention" data-mention="...">...</a>
    //
    // element.
    editor.conversion.for( 'downcast' ).attributeToElement( {
        model: 'mention',
        view: ( modelAttributeValue, { writer, options } ) => {
            // Do not convert empty attributes (lack of value means no mention).
            if ( !modelAttributeValue ) {
                return;
            }

            let href;

            // User mentions are downcasted as mailto: links. Tags become normal URLs.
            if ( modelAttributeValue.id[ 0 ] === '@' ) {
                href = `mailto:${ modelAttributeValue.id.slice( 1 ) }@example.com`;
            } else {
                href = `https://example.com/social/${ modelAttributeValue.id.slice( 1 ) }`;
            }

            return writer.createAttributeElement( 'a', {
                class: 'mention',
                'data-mention': modelAttributeValue.id,
                href,
                // Omit `data-mention-uid` in clipboard (copy/cut) to prevent UIDs duplication.
                ...( !options.isClipboardPipeline && { 'data-mention-uid': modelAttributeValue.uid } )
            }, {
                // Make mention attribute to be wrapped by other attribute elements.
                priority: 20,
                // Prevent merging mentions together in clipboard (when `data-mention-uid` is not available).
                id: modelAttributeValue.uid
            } );
        },
        converterPriority: 'high'
    } );
}

/*
 * Customizes the way the list of user suggestions is displayed.
 * Each user has an @id, a name and an avatar.
 */
function customItemRenderer( item ) {
    const itemElement = document.createElement( 'span' );
    const avatar = document.createElement( 'img' );
    const userNameElement = document.createElement( 'span' );
    const fullNameElement = document.createElement( 'span' );

    itemElement.classList.add( 'mention__item' );

    avatar.src = `https://ckeditor.com/docs/ckeditor5/latest/assets/img/${ item.avatar }.jpg`;

    userNameElement.classList.add( 'mention__item__user-name' );
    userNameElement.textContent = item.id;

    fullNameElement.classList.add( 'mention__item__full-name' );
    fullNameElement.textContent = item.name;

    itemElement.appendChild( avatar );
    itemElement.appendChild( userNameElement );
    itemElement.appendChild( fullNameElement );

    return itemElement;
}

```

View editor content listing 

```
<div class="chat">
    <ul class="chat__posts">
        <li>
            <img src="https://ckeditor.com/docs/ckeditor5/latest/assets/img/m_1.jpg" alt="avatar" class="photo">
            <div class="chat__posts__post__message">
                <strong>Charles Flores</strong>
                <a class="chat__posts__post__mailto-user" href="mailto:cflores@example.com">@cflores</a>
                <span class="chat__posts__post__time">2 hours ago</span>
                <p class="chat__posts__post__content">
                    Thanks for another <a class="mention" data-mention="#yummy" href="https://example.com/social/yummy">#yummy</a> recipe,
                    <a class="mention" data-mention="@dwilliams" href="mailto:dwilliams@example.com">@dwilliams</a>!
                    Makes me <a class="mention" data-mention="#hungry" href="https://example.com/social/hungry">#hungry</a>
                    just looking at the photos 😋. Definitely adding it to my TODO list for our next
                    <a class="mention" data-mention="#mediterranean" href="https://example.com/social/mediterranean">#mediterranean</a> potluck.
                </p>
            </div>
        </li>
        <li>
            <img src="https://ckeditor.com/docs/ckeditor5/latest/assets/img/w_1.jpg" alt="avatar" class="photo">
            <div class="chat__posts__post__message">
                <strong>Mildred Wilson</strong>
                <a class="chat__posts__post__mailto-user" href="mailto:mwilson@example.com">@mwilson</a>
                <span class="chat__posts__post__time">4 hours ago</span>
                <p class="chat__posts__post__content">
                    Really appreciate the <a class="mention" data-mention="#vegetarian" href="https://example.com/social/vegetarian">#vegetarian</a>
                    and <a class="mention" data-mention="#vegan" href="https://example.com/social/vegan">#vegan</a> variations of your recipes.
                    So thoughtful of you! 🌱
                </p>
            </div>
        </li>
    </ul>
    <div class="chat__editor">
        <p>
            I agree with <a href="mailto:mwilson@example.com" class="mention" data-mention="@mwilson">@mwilson</a> 👍.
            It’s so nice of you to always be providing a few options to try! I love
            <a href="https://example.com/social/greek" class="mention" data-mention="#greek">#greek</a> cuisine with a modern twist,
            this one will be perfect to try.
        </p>
    </div>

    <button class="chat-send" type="button">Send</button>
</div>

<style>
    /* ---- General layout ---------------------------------------------------------------------- */

    .chat {
        margin-bottom: 1em
    }

    /* ---- Chat posts -------------------------------------------------------------------------- */

    .chat ul.chat__posts {
        border: 1px solid var(--ck-color-base-border);
        border-top-left-radius: var(--ck-border-radius);
        border-top-right-radius: var(--ck-border-radius);
        border-bottom: none;
        margin: 1em 0 0;
        padding: 1em;
        list-style-position: inside;
    }

    .chat ul.chat__posts li {
        display: flex;
    }

    .chat ul.chat__posts li.new-post {
        /* Highlight a new post in the chat. */
        animation: highlight 600ms ease-out;
    }

    .chat ul.chat__posts li + li {
        margin-top: 1em;
    }

    .chat .chat__posts li .photo {
        border-radius: 100%;
        height: 40px;
        margin-right: 1.5em;
    }

    .chat .chat__posts li .time {
        color: hsl(0, 0%, 72%);
        font-size: .9em;
    }

    .chat .chat__posts .chat__posts__post__message > strong::after,
    .chat__posts__post__mailto-user::after {
        content: "•";
        padding-left: 5px;
        padding-right: 5px;
        color: hsl(0, 0%, 72%);
    }

    @keyframes highlight {
        0% {
            background-color: yellow;
        }

        100% {
            background-color: white;
        }
    }

    /* ---- Chat editor ------------------------------------------------------------------------- */

    .chat .chat__editor {
        /* Anti–FOUC (flash of unstyled content). */
        padding: 1em;
        border: 1px solid var(--ck-color-base-border);
    }

    .chat .chat__editor + .ck.ck-editor {
        margin-top: 0;
    }

    .chat .chat__editor + .ck.ck-editor .ck.ck-toolbar {
        border-top-left-radius: 0;
        border-top-right-radius: 0;
    }

    .chat .chat__editor + .ck.ck-editor .ck-content.highlighted {
        animation: highlight 600ms ease-out;
    }

    /* ---- In–editor mention list --------------------------------------------------------------- */

    .ck-mentions .mention__item {
        display: block;
    }

    .ck-mentions .mention__item img {
        border-radius: 100%;
        height: 30px;
    }

    .ck-mentions .mention__item span {
        margin-left: .5em;
    }

    .ck-mentions .mention__item.ck-on span {
        color: var(--ck-color-base-background);
    }

    .ck-mentions .mention__item .mention__item__full-name {
        color: hsl(0, 0%, 45%);
    }

    .ck-mentions .mention__item:hover:not(.ck-on) .mention__item__full-name {
        color: hsl(0, 0%, 40%);
    }

    /* ---- Chat editor content styles ----------------------------------------------------------- */

    .chat .ck-content .mention {
        background: unset;
    }

    .chat .ck.ck-content a,
    .chat .chat__posts a {
        color: hsl(231, 89%, 53%);
    }
</style>

```

<a id="ckeditor5/latest/examples/framework/custom-ui.html">source file: "ckeditor5/latest/examples/framework/custom-ui.html"</a>

## Custom UI (with Bootstrap)

The editor below runs a completely custom user interface written in [Bootstrap](http://getbootstrap.com/), while the editing is provided by CKEditor 5.

<a id="ckeditor5/latest/examples/framework/custom-ui.html--detailed-guide">

### Detailed guide

If you would like to create this interface on your own, read the [dedicated tutorial](#ckeditor5/latest/framework/deep-dive/ui/external-ui.html) that shows how to achieve this step by step with the source code provided.

<a id="ckeditor5/latest/examples/framework/theme-customization.html">source file: "ckeditor5/latest/examples/framework/theme-customization.html"</a>

## Theme customization

The default theme of CKEditor 5 can be customized to match most visual integration requirements.

Below, you can see an editor with the dark theme as a result of customizations described in a [dedicated guide](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html).

**Mode:**

<a id="ckeditor5/latest/examples/framework/theme-customization.html--theme-mode-light">

Light

<a id="ckeditor5/latest/examples/framework/theme-customization.html--theme-mode-dark">

Dark

<a id="ckeditor5/latest/examples/framework/theme-customization.html--detailed-guide">

### Detailed guide

If you would like to create such a widget on your own, read the [dedicated tutorial](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) that shows how to achieve this step by step with the source code provided.

<a id="ckeditor5/latest/examples/index.html">source file: "ckeditor5/latest/examples/index.html"</a>

## Examples

Check out these examples of different editor integrations. See the various editor types in action, witness the unharnessed power of a feature-rich preset, and find out amazing, custom-tailored implementations using the CKEditor 5 Framework.

<a id="ckeditor5/latest/examples/index.html--editor-types">

### Editor types

CKEditor 5 offers several rich text editor types. They cover the most common editing use cases, and you can install them easily. See all of them in action: [classic](#ckeditor5/latest/examples/builds/classic-editor.html), [inline](#ckeditor5/latest/examples/builds/inline-editor.html), [balloon](#ckeditor5/latest/examples/builds/balloon-editor.html), [balloon block](#ckeditor5/latest/examples/builds/balloon-block-editor.html), [document](#ckeditor5/latest/examples/builds/document-editor.html), and [multi-root](#ckeditor5/latest/examples/builds/multi-root-editor.html) editors! Learn their differences by using our examples.

<a id="ckeditor5/latest/examples/index.html--advanced-presets">

### Advanced presets

CKEditor 5 is a configurable framework created with collaboration in mind. It lets you build a custom editor of any type, with a wide set of features and the toolbar type that you need where multiple authors can easily work on the same rich text documents. Check out our [feature-rich editor](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) that sports as many plugins as possible to put together. Want to invite some friends? Try the [collaborative document editor](#ckeditor5/latest/examples/builds-custom/collaborative-document-editor.html) that brings the experience of the most popular online editing solutions to the table.

<a id="ckeditor5/latest/examples/index.html--advanced-configuration-ckeditor-5-framework-examples">

### Advanced configuration – CKEditor 5 Framework examples

[CKEditor 5 Framework](#ckeditor5/latest/framework/index.html) is a highly flexible and universal platform that provides a set of components allowing you to create any kind of rich text editor. It enables the integrators to build different, custom-tailored editing solutions with [custom UI](#ckeditor5/latest/examples/framework/custom-ui.html) or [a theme](#ckeditor5/latest/examples/framework/theme-customization.html) that suit their specific needs. It also provides tools for customizing [existing ones](#ckeditor5/latest/examples/framework/chat-with-mentions.html). And witness the flexibility of the UI in the [toolbar-oriented example](#ckeditor5/latest/examples/framework/bottom-toolbar-editor.html).

<a id="ckeditor5/latest/features/accessibility.html">source file: "ckeditor5/latest/features/accessibility.html"</a>

## Accessibility support

CKEditor 5 incorporates various accessibility features, including keyboard navigation, screen reader support (ARIA attributes), and robust semantic output markup. This guide provides a detailed overview and presents the current status of editor accessibility.

<a id="ckeditor5/latest/features/accessibility.html--conformance-with-wcag-2x-and-section-508">

### Conformance with WCAG 2.x and Section 508

CKEditor 5 is compliant with [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) (WCAG) 2.2 levels A and AA and [Section 508 of the Rehabilitation Act](https://www.access-board.gov/ict/) unless stated otherwise in the [Accessibility Conformance Report](#ckeditor5/latest/features/accessibility.html--accessibility-conformance-report-vpat).

* [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) (WCAG) provides international standards for making web content accessible to individuals with disabilities, ensuring that web applications are perceivable, operable, understandable, and robust for all users.
* [Section 508 of the Rehabilitation Act](https://www.access-board.gov/ict/) mandates that federal agencies’ electronic and information technology is accessible to people with disabilities, establishing guidelines to achieve this goal.

CKEditor 5 strives for conformance with these standards and we welcome your [feedback](#ckeditor5/latest/features/accessibility.html--accessibility-feedback-and-bugs) on the accessibility of our software.

<a id="ckeditor5/latest/features/accessibility.html--recommended-software">

### Recommended software

For optimal screen reader experience, we recommend using Google Chrome and NVDA (Windows) or Safari and VoiceOver (macOS).

<a id="ckeditor5/latest/features/accessibility.html--accessibility-conformance-report-vpat">

### Accessibility Conformance Report (VPAT)

In our ongoing commitment to accessibility, we provide a report based on the [ITI Voluntary Product Accessibility Template](https://www.itic.org/policy/accessibility/vpat) (VPAT\*\*®\*\*), a standardized format for evaluating the accessibility of computer software. This document serves as a comprehensive resource detailing the accessibility features of CKEditor 5, including compliance with accessibility standards and guidelines: [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) (WCAG) 2.2 levels A and AA and [Section 508 of the Rehabilitation Act](https://www.access-board.gov/ict/).

We continuously update the VPAT**®** report to reflect any changes or improvements. You can download the latest version of the VPAT**®** document below.

📎 [**Download VPAT® report for CKEditor 5 v44.3.0 (Mar 5, 2025)**](../assets/pdf/VPAT%5FCKEditor%5F5%5Fv44.3.0.pdf)

<a id="ckeditor5/latest/features/accessibility.html--previous-versions">

#### Previous versions

* 📎 [VPAT® report for CKEditor 5 v43.0.0 (Aug 7, 2024)](../assets/pdf/VPAT%5FCKEditor%5F5%5Fv43.0.0.pdf)
* 📎 [VPAT® report for CKEditor 5 v41.4.2 (May 17, 2024)](../assets/pdf/VPAT%5FCKEditor%5F5%5Fv41.4.2.pdf)
* 📎 [VPAT® report for CKEditor 5 v41.3.0 (Apr 10, 2024)](../assets/pdf/VPAT%5FCKEditor%5F5%5Fv41.3.0.pdf)

<a id="ckeditor5/latest/features/accessibility.html--keyboard-shortcuts">

### Keyboard shortcuts

CKEditor 5 supports various keyboard shortcuts that boost productivity and provide necessary accessibility to screen reader users.

Below is a list of the most important keystrokes supported by CKEditor 5 and its features.

<a id="ckeditor5/latest/features/accessibility.html--content-editing-keystrokes">

#### Content editing keystrokes

These keyboard shortcuts allow for quick access to content editing features.

| Action                                | PC                   | Mac                  |
| ------------------------------------- | -------------------- | -------------------- |
| Insert a hard break (a new paragraph) | Enter                |                      |
| Insert a soft break (a <br> element)  | Shift+Enter          | ⇧Enter               |
| Copy selected content                 | Ctrl+C               | ⌘C                   |
| Paste content                         | Ctrl+V               | ⌘V                   |
| Paste content as plain text           | Ctrl+Shift+V         | ⌘⇧V                  |
| Undo                                  | Ctrl+Z               | ⌘Z                   |
| Redo                                  | Ctrl+Y, Ctrl+Shift+Z | ⌘Y, ⌘⇧Z              |
| Bold text                             | Ctrl+B               | ⌘B                   |
| Change text case                      | Shift+F3             | ⇧F3 (may require Fn) |
| Create link                           | Ctrl+K               | ⌘K                   |
| Move out of a link                    | ←←, →→               |                      |
| Move out of an inline code style      | ←←, →→               |                      |
| Select all                            | Ctrl+A               | ⌘A                   |
| Find in the document                  | Ctrl+F               | ⌘F                   |
| Copy text formatting                  | Ctrl+Shift+C         | ⌘⇧C                  |
| Paste text formatting                 | Ctrl+Shift+V         | ⌘⇧V                  |
| Italic text                           | Ctrl+I               | ⌘I                   |
| Strikethrough text                    | Ctrl+Shift+X         | ⌘⇧X                  |
| Underline text                        | Ctrl+U               | ⌘U                   |
| Revert autoformatting action          | Backspace            |                      |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-for-interacting-with-annotation-threads-such-as-comments-or-track-changes-suggestions">

##### Keystrokes for interacting with annotation threads (such as comments or track changes suggestions)

| Action                                                                             | PC           | Mac    |
| ---------------------------------------------------------------------------------- | ------------ | ------ |
| Move focus to the thread when the selection is anchored in its marker              | Ctrl+Shift+E | ⌘⇧E    |
| Exit the annotation and move focus back to the edited content                      | Esc          |        |
| Browse the focused annotation thread or thread comment                             | Enter        |        |
| Move across internals of the annotation thread                                     | ⇥, Shift+⇥   | ⇥, ⇧⇥  |
| Submit the reply while writing a comment                                           | Ctrl+Enter   | ⌘Enter |
| Move to the previous or next thread in the annotations sidebar or comments archive | ↑, ↓         |        |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-can-be-used-when-a-widget-is-selected-such-as-image-table-etc">

##### Keystrokes that can be used when a widget is selected (such as image, table, etc.)

| Action                                                                                                                                                  | PC           | Mac    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
| Insert a new paragraph directly after a widget                                                                                                          | Enter        |        |
| Insert a new paragraph directly before a widget                                                                                                         | Shift+Enter  | ⇧Enter |
| Move the caret to allow typing directly before a widget                                                                                                 | ↑, ←         |        |
| Move the caret to allow typing directly after a widget                                                                                                  | ↓, →         |        |
| After entering a nested editable, move the selection to the closest ancestor widget. For example: move from an image caption to the whole image widget. | Tab then Esc |        |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-can-be-used-in-a-list">

##### Keystrokes that can be used in a list

| Action                    | PC      | Mac |
| ------------------------- | ------- | --- |
| Increase list item indent | ⇥       |     |
| Decrease list item indent | Shift+⇥ | ⇧⇥  |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-for-navigating-through-documents">

##### Keystrokes for navigating through documents

| Action                                        | PC              | Mac                         |
| --------------------------------------------- | --------------- | --------------------------- |
| Go to the previous page (also move selection) | Shift+Page Up   | ⇧Page Up (may require Fn)   |
| Go to the next page (also move selection)     | Shift+Page Down | ⇧Page Down (may require Fn) |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-can-be-used-in-a-table-cell">

##### Keystrokes that can be used in a table cell

| Action                                                    | PC         | Mac |
| --------------------------------------------------------- | ---------- | --- |
| Move the selection to the next cell                       | ⇥          |     |
| Move the selection to the previous cell                   | Shift+⇥    | ⇧⇥  |
| Insert a new table row (when in the last cell of a table) | ⇥          |     |
| Navigate through the table                                | ↑, →, ↓, ← |     |

<a id="ckeditor5/latest/features/accessibility.html--user-interface-and-content-navigation-keystrokes">

#### User interface and content navigation keystrokes

Use the following keystrokes for more efficient navigation in the CKEditor 5 user interface.

| Action                                                                                                                             | PC             | Mac                   |
| ---------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------- |
| Close contextual balloons, dropdowns, and dialogs                                                                                  | Esc            |                       |
| Open the accessibility help dialog                                                                                                 | Alt+0          | ⌥0                    |
| Move focus between form fields (inputs, buttons, etc.)                                                                             | ⇥, Shift+⇥     | ⇥, ⇧⇥                 |
| Move focus to the toolbar, navigate between toolbars                                                                               | Alt+F10        | ⌥F10 (may require Fn) |
| Navigate through the toolbar or menu bar                                                                                           | ↑, →, ↓, ←     |                       |
| Navigate to the next focusable field or an element outside the editor                                                              | Tab, Shift+Tab |                       |
| Execute the currently focused button. Executing buttons that interact with the editor content moves the focus back to the content. | Enter, Space   |                       |
| Move focus to the menu bar, navigate between menu bars                                                                             | Alt+F9         | ⌥F9 (may require Fn)  |
| Move focus in and out of an active dialog window                                                                                   | Ctrl+F6        | ⌘F6 (may require Fn)  |

<a id="ckeditor5/latest/features/accessibility.html--source-editing-enhanced-plugin">

#### Source Editing Enhanced (plugin)

Keystrokes introduced by [Source Editing Enhanced plugin](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html), to streamline code editing experience.

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-related-to-the-built-in-code-completion-mechanism">

##### Keystrokes related to the built-in code completion mechanism

| Action                                         | PC        | Mac |
| ---------------------------------------------- | --------- | --- |
| Accept completion                              | Enter     |     |
| Close completion                               | Esc       |     |
| Move completion selection backward             | ↑         |     |
| Move completion selection backward by one page | Page Up   |     |
| Move completion selection forward              | ↓         |     |
| Move completion selection forward by one page  | Page Down |     |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-related-to-the-built-in-code-folding-mechanism">

##### Keystrokes related to the built-in code folding mechanism

| Action      | PC            | Mac  |
| ----------- | ------------- | ---- |
| Fold all    | Ctrl+Alt+\[   | ⌃⌥\[ |
| Fold code   | Ctrl+Shift+\[ | ⌘⌥\[ |
| Unfold all  | Ctrl+Alt+\]   | ⌃⌥\] |
| Unfold code | Ctrl+Shift+\] | ⌘⌥\] |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-change-the-selection-in-the-code-editor">

##### Keystrokes that change the selection in the code editor

| Action                        | PC              | Mac             |
| ----------------------------- | --------------- | --------------- |
| Select all                    | Ctrl+A          | ⌘A              |
| Select character left         | Shift+←         | ⇧←, ⌃⇧B         |
| Select character right        | Shift+→         | ⇧→, ⌃⇧F         |
| Select document end           | Shift+Ctrl+End  | ⌘⇧↓, ⌘⇧End      |
| Select document start         | Shift+Ctrl+Home | ⌘⇧↑, ⌘⇧Home     |
| Select group left             | Shift+Ctrl←     | ⌥⇧←             |
| Select group right            | Shift+Ctrl→     | ⌥⇧→             |
| Select line                   | Alt+L           | ⌃L              |
| Select line boundary backward | Shift+Home      | ⇧Home           |
| Select line boundary forward  | Shift+End       | ⇧End            |
| Select line down              | Shift+↓         | ⇧↓, ⌃⇧N         |
| Select line up                | Shift+↑         | ⇧↑, ⌃⇧P         |
| Select page down              | Shift+Page Down | ⌃⇧↓, ⇧Page Down |
| Select page up                | Shift+Page Up   | ⌃⇧↑, ⇧Page Up   |
| Select parent syntax          | Ctrl+I          | ⌘I              |
| Select syntax left            | Shift+Alt+←     | ⌃⇧←             |
| Select syntax right           | Shift+Alt+→     | ⌃⇧→             |
| Select line boundary left     |                 | ⌘⇧←             |
| Select line boundary right    |                 | ⌘⇧→             |
| Select line end               |                 | ⌃⇧E             |
| Select line start             |                 | ⌃⇧A             |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-move-the-cursor-caret-in-the-code-editor">

##### Keystrokes that move the cursor (caret) in the code editor

| Action                                | PC           | Mac               |
| ------------------------------------- | ------------ | ----------------- |
| Move cursor to character left         | ←            | ←, ⌃B             |
| Move cursor to character right        | →            | →, ⌃F             |
| Move cursor to document end           | Ctrl+End     | ⌘↓, ⌘End          |
| Move cursor to document start         | Ctrl+Home    | ⌘↑, ⌘Home         |
| Move cursor to group left             | Ctrl+←       | ⌥←                |
| Move cursor to group right            | Ctrl+→       | ⌥→                |
| Move cursor to line boundary backward | Home         |                   |
| Move cursor to line boundary forward  | End          |                   |
| Move cursor to line down              | ↓            | ↓, ⌃N             |
| Move cursor to line up                | ↑            | ↑, ⌃P             |
| Move cursor to matching bracket       | Shift+Ctrl\\ | ⌘⇧\\              |
| Move cursor to page down              | Page Down    | ⌃↓, ⌃V, Page Down |
| Move cursor to page up                | Page Up      | ⌃↑, Page Up       |
| Move cursor to syntax left            | Alt+←        | ⌃←                |
| Move cursor to syntax right           | Alt+→        | ⌃→                |
| Move line down                        | Alt+↓        | ⌥↓                |
| Move line up                          | Alt+↑        | ⌥↑                |
| Move cursor to line boundary left     |              | ⌘←                |
| Move cursor to line boundary right    |              | ⌘→                |
| Move cursor to line end               |              | ⌘E                |
| Move cursor to line start             |              | ⌘A                |

<a id="ckeditor5/latest/features/accessibility.html--keystrokes-that-modify-the-code-in-the-editor">

##### Keystrokes that modify the code in the editor

| Action                        | PC                         | Mac                       |
| ----------------------------- | -------------------------- | ------------------------- |
| Copy line down                | Shift+Alt+↓                | ⇧⌥↓                       |
| Copy line up                  | Shift+Alt+↑                | ⇧⌥↑                       |
| Delete bracket pair           | Backspace                  |                           |
| Delete character backward     | Backspace, Shift+Backspace | Backspace, ⌃H, ⇧Backspace |
| Delete character forward      | Delete                     | ⌃D, Delete                |
| Delete group backward         | Ctrl+Backspace             | ⌥Backspace, ⌃⌥H           |
| Delete group forward          | Ctrl+Delete                | ⌥Delete                   |
| Delete line                   | Shift+CtrlK                | ⌘⇧K                       |
| Indent less                   | Ctrl+\[                    | ⌘\[                       |
| Indent more                   | Ctrl+\]                    | ⌘\]                       |
| Indent selection              | Ctrl+Alt+\\                | ⌘⌥\\                      |
| Insert blank line             | Ctrl+Enter                 | ⌘Enter                    |
| Insert new line and indent    | Enter, Shift+Enter         | Enter, ⇧Enter             |
| Redo                          | Ctrl+Shift+Z, Ctrl+Y       | ⌘⇧Z, ⌘Y                   |
| Redo selection                | Alt+U                      | ⌘⇧U                       |
| Simplify selection            | Esc                        |                           |
| Toggle block comment          | Shift+Alt+A                | ⇧⌥A                       |
| Toggle comment                | Ctrl+/                     | ⌘/                        |
| Undo                          | Ctrl+Z                     | ⌘Z                        |
| Undo selection                | Ctrl+U                     | ⌘U                        |
| Delete line boundary backward |                            | ⌘Backspace                |
| Delete line boundary forward  |                            | ⌘Delete                   |
| Delete to line end            |                            | ⌃K                        |
| Split line                    |                            | ⌃O                        |
| Transpose characters          |                            | ⌃T                        |

<a id="ckeditor5/latest/features/accessibility.html--miscellaneous-code-editor-shortcuts">

##### Miscellaneous code editor shortcuts

| Action                                                     | PC     | Mac |
| ---------------------------------------------------------- | ------ | --- |
| Switch between "focus with tab" and "indent with tab" mode | Ctrl+M | ⌥⇧M |

<a id="ckeditor5/latest/features/accessibility.html--displaying-keyboard-shortcuts-in-the-editor">

#### Displaying keyboard shortcuts in the editor

CKEditor 5 offers a dedicated [Accessibility help](../api/module%5Fui%5Feditorui%5Faccessibilityhelp%5Faccessibilityhelp-AccessibilityHelp.html) plugin that displays a list of all available keyboard shortcuts in a dialog. It can be opened by pressing Alt \+ 0 (on Windows) or ⌥0 (on macOS). Alternatively, you can use the toolbar button to open the dialog.

The Accessibility help plugin is enabled by the [Essentials](../api/module%5Fessentials%5Fessentials-Essentials.html) plugin from the [@ckeditor/ckeditor5-essentials](https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/api/essentials.html) package (which also enables other common editing features).

Learn how integrators can [add keyboard shortcuts to their features](#ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--adding-keyboard-shortcuts) and [supply shortcut information](#ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--adding-shortcut-information-to-the-accessibility-help-dialog) to the Accessibility help dialog.

<a id="ckeditor5/latest/features/accessibility.html--accessibility-feedback-and-bugs">

### Accessibility feedback and bugs

We welcome your feedback on the accessibility of CKEditor 5\. You can find the [current list of accessibility issues](https://github.com/ckeditor/ckeditor5/issues?q=is%3Aopen+is%3Aissue+label%3Adomain%3Aaccessibility) on GitHub. Learn how to [report issues](#ckeditor5/latest/support/index.html--reporting-issues).

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html">source file: "ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html"</a>

## Integrating AI Assistant with your application

This guide will take you step-by-step through the process of running AI Assistant in your editor integration. It also presents possible configuration and customization options.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--supported-ai-services">

### Supported AI services

First, you will need to decide which AI service provider you want to integrate with. CKEditor does not provide the AI model itself. Instead, the feature relies on an external service to provide AI-generated responses.

We offer support for two leading platforms that provide AI services: **OpenAI and Azure OpenAI.**

Since the feature relies on an external provider, the quality of the responses depends on that provider and their model.

If you have no constraints regarding the platform that you can use, **we recommend integrating with the OpenAI API**. It provides better quality and is the simplest to set up.

This guide includes tips on how to set up the supported AI platforms. We expect that the integrator knows how their chosen platform works and how to configure it to best fit their use case.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--using-proxy-endpoint">

### Using proxy endpoint

Before moving to the integration, there is one more subject to cover.

There are two general approaches to how the feature can communicate with the AI service provider: directly, or using an endpoint in your application.

Direct connection is simpler to set up and should not involve changes in your application’s backend. It is recommended for development purposes. AI Assistant supports this, as it makes it easier for you to test the feature without committing time to set up the backend part of the integration.

**However, this method exposes your private authorization data which is a serious security issue. You should never use it in the production environment.**

In the final solution, your application should provide an endpoint that the AI Assistant will call instead of calling the AI service directly. The main goal of this endpoint is to hide the authorization data from the editor users. The request to the AI service should happen from your backend, without exposing authorization credentials.

The application endpoint is also a good place to implement additional functionalities, like request customization, user billing, or logging statistics.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--integration">

### Integration

In the next step, you will need to set up the AI service of your choice and integrate the editor to use it:

* [OpenAI integration](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--openai-integration)
* [Azure OpenAI integration](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--azure-openai-integration)

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--openai-integration">

#### OpenAI integration

This section describes how to integrate the AI Assistant with the [OpenAI platform](https://openai.com/).

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--set-up-the-account">

##### Set up the account

[Create](https://platform.openai.com/login?launch) an OpenAI account and get your [OpenAI API](https://help.openai.com/en/articles/4936850-where-do-i-find-my-secret-api-key) key.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--making-connection">

##### Making connection

To connect to the OpenAI service, you will need to add a connection adapter plugin to the editor. The adapter is responsible for making requests in the correct format and handling the responses.

Import the [OpenAITextAdapter](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapter.html) plugin from the `ckeditor5-ai` package and add it to the list of plugins.

Then, add the OpenAI key to the editor configuration.

You should send the key in the request “Authorization” header. You can set the request headers using the [config.ai.assistant.adapter.openAI.requestHeaders](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapterConfig.html#member-requestHeaders) configuration property.

The snippet below presents the described changes:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            assistant: {
                adapter: {
                    openAI: {
                        requestHeaders: {
                            // Paste your OpenAI API key in place of YOUR_OPENAI_API_KEY:
                            Authorization: 'Bearer YOUR_OPENAI_API_KEY'
                        }
                    }
                }
                // ...
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This is the minimal setup required to launch AI Assistant. **You can test it now.**

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--request-parameters">

##### Request parameters

You can further configure how the OpenAI adapter works using the [config.ai.assistant.adapter.openAI.requestParameters](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapterConfig.html#member-requestParameters) option:

* Choose the exact OpenAI model to use.
* Set whether the response should be streamed (simulating the “writing” experience) or returned all at once.
* Fine-tune the model behavior.

See the [OpenAI reference](https://platform.openai.com/docs/api-reference/chat/create) to learn what parameters you can use and how they affect the responses.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--supported-models">

##### Supported models

By default, the OpenAI adapter will use the GPT-4o model.

CKEditor 5 supports all recent GPT-3.5 and GPT-4 models as well as legacy models (version `0613`).

You can find more information about offered models in the [OpenAI documentation](https://platform.openai.com/docs/models/).

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--integrating-with-the-proxy-endpoint">

##### Integrating with the proxy endpoint

As [described earlier](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--using-proxy-endpoint), before moving to production, you should create an endpoint that will communicate with the OpenAI service, instead of connecting directly and exposing your OpenAI API key.

For the OpenAI integration, you can implement the endpoint, in its simplest form, as a transparent proxy service. The service will get the requests from the editor, add authorization headers to them, and pass them to the AI service. Then, you should pass all responses back to the editor.

After you implemented the endpoint, set the URL to your endpoint using the [config.ai.assistant.adapter.openAI.apiUrl](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapterConfig.html#member-apiUrl) option. Also, remember to remove the OpenAI key from the configuration:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            assistant: {
                adapter: {
                    openAI: {
                        apiUrl: 'https://url.to.your.application/ai'
                    }
                }
                // ...
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Now, all requests are redirected to `'https://url.to.your.application/ai'`.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--additional-authorization-and-custom-headers">

##### Additional authorization and custom headers

Depending on your application, it might be necessary to pre-authorize the request before sending it to your application endpoint. One of the common patterns is to use JSON Web Token (JWT) authorization.

This, and similar cases, are supported through the [config.ai.assistant.adapter.openAI.requestHeaders](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapterConfig.html#member-requestHeaders) option. You can set it to an object or an asynchronous function that resolves with an object. The object is then set as the request headers.

You can set `config.ai.assistant.adapter.openAI.requestHeaders` to a function that queries the authorization API and sets the returned JWT in an authorization header:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            assistant: {
                adapter: {
                    openAI: {
                        apiUrl: 'https://url.to.your.application/ai',
                        requestHeaders: async () => {
                            const jwt = await fetch( 'https://url.to.your.auth.endpoint/' );

                            return {
                                Authorization: 'Bearer ' + jwt
                            };
                        }
                    }
                }
                // ...
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

You can pass the [actionId](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html#member-actionId) parameter to the `requestHeaders` function. It identifies the action that the user performed. This allows for further customization on your end.

```
{
    requestHeaders: async ( actionId ) => {
        const jwt = await fetch( 'https://url.to.your.auth.endpoint/?actionId=' + actionId );

        return {
            Authorization: 'Bearer ' + jwt
        };
    }
}

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--advanced-customization">

##### Advanced customization

The most flexible place to apply request processing customization is your application endpoint. However, if for any reason you cannot customize the request on your application’s backend, you can consider the following extension points on the editor side.

**Dynamic request headers.**

As mentioned earlier, you can provide `config.ai.assistant.adapter.openAI.requestHeaders` as an asynchronous function that can make a call to your application. You can use the [actionId](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html#member-actionId) parameter for further customization.

**Dynamic request parameters.**

Similarly to request headers, you can provide `config.ai.assistant.adapter.openAI.requestParameters` as an asynchronous function. The function is also passed the [actionId](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html#member-actionId). You can return different parameters based on it. For example, you can use different models for different actions.

**Customizing [request messages](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages).**

The request messages passed to the OpenAI service are built based on how the user used the feature: the selected content and the provided query.

You can overload the [OpenAITextAdapter#prepareMessages()](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapter.html#function-prepareMessages) method to customize the request messages or provide custom logic that will create the request messages.

For example:

* You can fine-tune the system message for specific (or your custom) predefined commands.
* You can pre-query your application to get extra context information and add it as an additional message.
* You can get additional context or data from the editor, document data, or your custom features.
* You can alter or redact parts of the `context` before sending it to the service.

Remember to add `CustomOpenAITextAdapter` to the plugin list instead of `OpenAITextAdapter`.

**Altering AI service responses**

Each feature that sends a request provides the [onData()](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html#member-onData) callback. The callback is executed each time the adapter receives the data from the AI service. You can decorate this callback to customize the response.

This will require overloading the [OpenAITextAdapter#sendRequest()](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapter.html#function-sendRequest) method and changing the `requestData.onData` parameter:

If the adapter works in the streaming mode, the `content` will include a partial, accumulating response. This may bring some extra complexity to your custom handling.

Remember to add `CustomOpenAITextAdapter` to the plugin list instead of `OpenAITextAdapter`.

**Overloading the [sendRequest()](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapter.html#function-sendRequest) method.**

You can overload the `sendRequest()` method to add some processing before or after making the call.

Remember to add `CustomOpenAITextAdapter` to the plugin list instead of `OpenAITextAdapter`.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--azure-openai-integration">

#### Azure OpenAI integration

This section describes how to integrate the AI Assistant with the [Azure OpenAI Service](https://azure.microsoft.com/en-us/products/ai-services/openai-service).

Microsoft’s Azure platform provides many AI-related services. AI Assistant supports only the OpenAI models.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--set-up-the-service">

##### Set up the service

First, you will need to create an [Azure](https://azure.microsoft.com/) account if you do not already own one.

You need to follow these steps to set up the AI Assistant:

* Log in to your Azure account.
* Create an “Azure OpenAI” resource.
* Go to the “Azure OpenAI” resource and open “Keys and Endpoint” to find your API key(s).
* Go to “Model deployments” and then create a deployment. Select the model and the name you want to use for that deployment.
* You will need the resource name, API key, and deployment name to configure the AI Assistant.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--making-connection-2">

##### Making connection

To connect to the Azure OpenAI service, you will need to add a connection adapter plugin to the editor. The adapter is responsible for making requests in the correct format and handling the responses.

Import the [OpenAITextAdapter](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapter.html) plugin from the `ckeditor5-ai` package and add it to the list of plugins.

Then, you will need to configure the AI Assistant, so it connects to the Azure OpenAI service using your data:

* The request URL as specified in the [Azure OpenAI reference](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#chat-completions) (it will include your deployment name and the API version).  
  * We tested AI Assistant with the `2023-12-01-preview` API version.
* You need to pass the API key in the request `api-key` header.

The snippet below presents the described changes:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            assistant: {
                adapter: {
                    openAI: {
                        // Paste your resource name, deployment name, and API version
                        // in place of YOUR_RESORCE_NAME, YOUR_DEPLOYMENT_NAME, and YOUR_API_VERSION:
                        apiUrl: 'https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=YOUR_API_VERSION',
                        requestHeaders: {
                            'api-key': 'YOUR_AZURE_OPEN_AI_API_KEY'
                        }
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This is the minimal setup required to launch AI Assistant. **You can test it now.**

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--request-parameters-2">

##### Request parameters

You can further configure how the OpenAI adapter works using the [config.ai.assistant.adapter.openAI.requestParameters](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Fopenaitextadapter-OpenAITextAdapterConfig.html#member-requestParameters) option:

* Set whether the response should be streamed (simulating the “writing” experience) or returned all at once.
* Fine-tune the model behavior.

See the [Azure OpenAI reference](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#chat-completions) to learn what parameters you can use and how they affect the responses.

You may also set `requestParameters` to an asynchronous function. In this case, it should resolve with an object that contains the parameters. The function receives [actionId](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html#member-actionId) as a parameter, which identifies the action that the user performed. This allows for further customization on your end.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--supported-models-and-api-versions">

##### Supported models and API versions

CKEditor 5 supports all recent GPT-3.5 and GPT-4 models as well as legacy models (version `0613`).

You can find more information about offered models in the [Azure OpenAI documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models).

The most recent tested API version is `2023-12-01-preview`.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--integrating-with-proxy-endpoint">

##### Integrating with proxy endpoint

As [described earlier](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--using-proxy-endpoint), before moving to production, you should create an endpoint that will communicate with the OpenAI service, instead of connecting directly and exposing your OpenAI API key.

See the [“Integration with the proxy endpoint” section for the OpenAI integration](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--integrating-with-the-proxy-endpoint), as the process is the same for both platforms.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--advanced-customization-2">

##### Advanced customization

The most flexible place to apply request processing customization is your application endpoint. However, if for any reason you cannot customize the request on your application’s backend, you can extend the `OpenAITextAdapter`. There are many extension points which you may consider.

See the [“Advanced customization” section for the OpenAI integration](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--advanced-customization), as it is the same for both platforms.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--amazon-bedrock-integration">

#### Amazon Bedrock integration

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--custom-models">

#### Custom models

You can integrate AI Assistant with any service of your choice as well as your custom models.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--use-openai-adapter-and-adjust-ai-service-responses">

##### Use OpenAI adapter and adjust AI service responses

A simple way to provide support for a different AI model or service is to use the [OpenAI integration](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--openai-integration), and then [provide an endpoint](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--integrating-with-the-proxy-endpoint) in your application that will query the chosen model or service. You need to make sure that the responses passed to the adapter are in the same format as the OpenAI API responses.

In the end, the adapter remains indifferent to what endpoint you connect to. Its role is to create the request data and handle the response. As long as the response format is the same as the one used by the OpenAI API, it will work.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--implement-custom-adapter">

##### Implement custom adapter

Another method to support different models is to provide a custom implementation of the [AITextAdapter](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapter.html) plugin.

This will give you more flexibility in creating the request and processing the response. The full implementation will depend on the requirements set by the chosen AI model.

Start with defining your custom adapter class:

From the editor’s perspective, you will need to implement the [sendRequest()](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapter.html#function-sendRequest) method:

This is the place where you should handle the request. The [requestData](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faitextadapter-AITextAdapterRequestData.html) parameter includes the data provided by the feature (for example, AI Assistant) as the feature made the call to the adapter.

The API documentation describes each part of `requestData`. To better understand it, here is a breakdown using the AI Assistant as an example:

* `query` – The predefined command query or custom query provided by the user. The instruction for the AI model.
* `context` – The HTML content selected in the editor when the user made the request. It may be empty.
* `actionId` – For AI Assistant this could be `aiAssistant:custom` or `aiAssistant:command:<commandId>`. You can use it to handle various user actions differently.
* `onData` – For AI Assistant, it updates the UI (response area) and saves the updated response in the feature’s internals. You should call it each time the adapter gets an update from the AI service.

In short, you should use `query` and `context` (and optionally `actionId`) to build a prompt for the AI service. Then call `onData()` when you receive a response. It could happen once (no streaming) or many times (streaming). Support for streaming depends on the AI service.

Alternatively, you can pass `query`, `context`, and `actionId` in the request to your application endpoint and handle them on the backend.

When your adapter fails for some reason, you should throw [AIRequestError](../../../api/module%5Fai%5Faiassistant%5Fadapters%5Faiadapter-AIRequestError.html). The error will be handled by the feature. In the case of AI Assistant, it will be displayed in a red notification box.

Finally, add `CustomAITextAdapter` to the editor plugin list. Note, that you do not need to add any other adapter:

```
ClassicEditor
    .create( {
        plugins: [ AIAssistant, CustomAITextAdapter, /* ... */ ],
        /* .. */
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If the custom AI model supports streaming, you will receive the response in multiple small chunks. Make sure that each time the `onData()` callback is called, the value passed to it contains the full response. It needs to be a sum of the current update and all previously received responses.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--configuration-and-styling">

### Configuration and styling

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--adding-ai-commands-to-the-list">

#### Adding AI commands to the list

The **“AI Commands”** button  allows quick access to the most common AI Assistant commands. You can extend the [default list of commands](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-commands) or define your list.

Use the [config.ai.assistant.extraCommandGroups](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-extraCommandGroups) configuration option to extend the default list of commands:

```
ClassicEditor
    .create( {
        ai: {
            // AI Assistant feature configuration.
            assistant: {
                // Extend the default commands configuration.
                extraCommandGroups: [
                    // Add a command to an existing group:
                    {
                        groupId: 'translate',
                        commands: [
                            {
                                id: 'translatePolish',
                                label: 'Translate to Polish',
                                prompt: 'Translate to Polish language.'
                            }
                        ]
                    },
                    // Create a new AI commands group:
                    {
                        groupId: 'transformations',
                        groupLabel: 'Transformations',
                        commands: [
                            {
                                id: 'addEmojis',
                                label: 'Add emojis',
                                prompt: 'Analyze each sentence of this text. After each sentence add an emoji that summarizes the sentence.'
                            },
                            // ...
                        ]
                    },
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Use the [config.ai.assistant.commands](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-commands) configuration option to create the list of commands from scratch:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            // AI Assistant feature configuration.
            assistant: {
                // Define the commands list from scratch.
                commands: [
                    // Command groups keep them organized on the list.
                    {
                        groupId: 'customGroupId',
                        groupLabel: 'My group of commands',
                        commands: [
                            {
                                id: 'translateSpanish',
                                label: 'Translate to Spanish',
                                prompt: 'Translate this text to Spanish.'
                            },
                            {
                                id: 'explainFive',
                                label: 'Explain like I\'m five',
                                prompt: 'Explain this like I\'m five years old.'
                            },
                            // ...
                        ]
                    },
                    // You can add more command groups here.
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Please note that you can avoid creating command groups by passing commands definitions directly to the `ai.assistant.commands` configuration key. This will result in a flat list in the user interface.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--removing-default-commands-from-the-list">

#### Removing default commands from the list

You can use the [config.ai.assistant.removeCommands](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-removeCommands) configuration to remove some [default commands and command groups](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-commands) from the list:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            // AI Assistant feature configuration.
            assistant: {
                // Remove some of the default commands.
                removeCommands: [
                    // Use command id to remove a single command.
                    'improveWriting',
                    // Use groupId to remove entire command group.
                    'changeTone',
                    // ...
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--removing-the-violet-tint-from-the-ui">

#### Removing the violet tint from the UI

By default, some parts of the UI come with a violet tint that distinguishes the AI Assistant from the rest of CKEditor 5 features. If you do not want this styling in your integration, you can remove it by setting the [config.ai.assistant.useTheme](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html) configuration to `false`:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ai: {
            assistant: {
                // Remove the default feature's theme.
                useTheme: false
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--using-custom-colors-for-the-ui">

#### Using custom colors for the UI

You can customize the looks of the AI Assistant UI by using CSS custom properties. Below is the full list of CSS variables that you can set.

For instance, you can use the following CSS snippet to change the tint color to red:

```
.ck-ai-assistant-ui_theme {
    --ck-color-button-default-hover-background: hsl(0, 100%, 96%);
    --ck-color-button-default-active-background: hsl(0,100%,96.3%);
    --ck-color-button-on-background: hsl(0,100%,96.3%);
    --ck-color-button-on-hover-background: hsl(0,60%,92.2%);
    --ck-color-button-on-active-background: hsl(0,100%,96.3%);
    --ck-color-button-on-disabled-background: hsl(0,100%,96.3%);
    --ck-color-button-on-color: hsl(0,59.2%,52%);
    --ck-color-button-action-background: hsl(0,59.2%,52%);
    --ck-color-button-action-hover-background: hsl(0,58.9%,49.6%);
    --ck-color-button-action-active-background: hsl(0,58.9%,49.6%);
    --ck-color-button-action-disabled-background: hsl(0,59.3%,75.9%);
    --ck-color-list-button-hover-background: hsl(0,100%,96.3%);
    --ck-color-ai-selection: hsl(0,60%,90%);
}

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--changing-the-width-of-the-dialog">

#### Changing the width of the dialog

Use the following CSS snippet to widen the AI Assistant pop-up dialog:

```
.ck.ck-ai-form {
    --ck-ai-form-view-width: 800px;
}

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--changing-the-height-of-the-response-area">

#### Changing the height of the response area

Use the following CSS snippet to increase the `max-height` CSS property of the response content area and display more content to the users:

```
.ck.ck-ai-form {
    --ck-ai-form-content-height: 500px;
}

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--styling-the-ai-response-area">

#### Styling the AI response area

By default, the AI Assistant’s response content area comes with the `.ck-content` CSS class. This makes it possible for the users to see the response styled in the same way as the main editor content (learn more about it in the [Content styles](#ckeditor5/latest/getting-started/setup/css.html) guide).

However, if your integration uses custom styles outside the `.ck-content` class scope, and you want to apply them in the Assistant’s response content area, you can use [config.ai.assistant.contentAreaCssClass](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-contentAreaCssClass) and specify an additional class name (or names) for the element.

Styling the AI Assistant’s response content area is also possible via the `.ck.ck-ai-form .ck.ck-ai-form__content-field` selector:

```
.ck.ck-ai-form .ck.ck-ai-form__content-field h2 {
    /* Custom <h2> styles. */
}

```

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html">source file: "ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html"</a>

## AI Assistant (legacy)

AI Assistant provides a way to boost your editing efficiency and creativity through the use of AI (“artificial intelligence”) capabilities. Users can generate new content and process the data using custom queries, or choose an action from the predefined list of commands, which you can also configure to your liking.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--demo">

### Demo

* Select some content and press the **“AI Commands”** button  in the toolbar to get access to the most common tasks such as “Improve writing” or “Summarize.”
* Press the **“AI Assistant”** button  and provide your query for the AI. Here are a few ideas you might try:

  * ”Write a detailed guide for a one-day walking tour of Barcelona.”
  * ”List the top 5 keywords related to traveling.”
  * Select the table in the content below, then ask: “Fill empty cells with correct values.”

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--ui-colors-color-coding">

### UI colors (color coding)

The distinctive violet tint used in the AI Assistant’s user interface sets it apart from other (non-AI) features within the CKEditor 5 ecosystem. This use of color coding enhances user experience and provides clear visual cues. Thanks to this, users can easily tell which actions are AI-powered and what results they can expect.

All future AI-driven functionalities in CKEditor 5 will also use this color-coding approach. This includes possible smaller AI-related integrations in the existing features.

You can [remove](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--removing-the-violet-tint-from-the-ui) or [customize](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--using-custom-colors-for-the-ui) the violet tint to meet the needs of your integration.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--integration">

### Integration

AI Assistant relies on an external service to provide AI-generated responses. You will need to have access to such a service.

The feature supports integration with AI API providers: OpenAI and Azure OpenAI. You can also integrate it with custom models.

Read the AI Assistant [integration guide](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html) to learn more.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--customization">

### Customization

You can customize the feature to better fit your needs, for example:

* Change the list of the predefined commands by adding new ones or removing existing ones.
* Change the UI colors, styling, and sizes.

Read the AI Assistant [configuration and styling guide](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-integration.html--configuration-and-styling) to learn more.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--data-filtering-in-responses">

### Data filtering in responses

The AI response will only incorporate HTML elements and features that are compatible with the editor. For instance, if an AI Assistant response contains `<b>Bold text</b>`, your editor needs the [Bold](../../../api/module%5Fbasic-styles%5Fbold-Bold.html) plugin to be loaded to preserve it.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--query-history">

### Query history

The AI Assistant’s custom query field has a dedicated history button  that gives you access to your previous queries. It displays the last 20 queries and makes it possible to reuse and improve recent queries. The history is stored in the browser’s [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage). The session storage is separate for each browser tab and the browser clears it when you close the tab.

A user can also manually clear the query history by clicking the “Clear” button in the history dropdown.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--known-issues-and-caveats">

### Known issues and caveats

**Integration with some features**

The AI Assistant feature will be inactive if the current selection contains one of the following elements: media embed, HTML embed, or table of contents.

You can overwrite the list of features where the AI Assistant is inactive by changing the [config.ai.assistant.disabledElements](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-disabledElements) configuration property.

**Comments and suggestions**

When the AI model processes the selected content, it removes all markers. This means all comments and suggestions will be removed in the AI response.

**Broken images in the responses**

The AI model, if asked directly, may return image elements linking to non-existing images, which will appear broken in the response and in the editor content after being inserted.

**Integration with custom features**

Due to the nature of the technology behind this feature, you may get unexpected results when processing content that includes custom features that you have developed.

The AI model will try to process the HTML data according to how it was trained. However, if your feature creates a complex HTML structure or custom HTML tags, there is a higher chance that these will not be processed correctly.

If you experience problems with your custom features, you might turn off AI Assistant when they are selected by changing the [config.ai.assistant.disabledElements](../../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-disabledElements) configuration property.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you boost productivity:

* [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html) – CKEditor AI provides a way to boost your editing efficiency and creativity through the use of AI.
* [Automatic text transformations](#ckeditor5/latest/features/text-transformation.html) – Automatically change predefined text fragments into their improved forms.

<a id="ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--common-api">

### Common API

The [AIAssistantUI](../../../api/module%5Fai%5Faiassistant%5Faiassistantui-AIAssistantUI.html) plugin registers:

* The `'aiCommands'` UI dropdown component.
* The `'aiAssistant'` UI button component.
* The ['showAIAssistant' command](../../../api/module%5Fai%5Faiassistant%5Fui%5Fshowaiassistantcommand-ShowAIAssistantCommand.html).

You can execute the command to display the AI Assistant:

```
editor.execute( 'showAIAssistant' );

```

You can also display the AI Assistant and automatically submit the query to the AI service:

```
editor.execute( 'showAIAssistant', 'The query sent to the AI service', 'Label to display in the query field' );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-actions.html"</a>

## AI Quick Actions

AI Quick Actions streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in the Chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks. The feature comes with an easy-to-use window interface but can also act as a conversation starter with the [Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--demo">

### Demo

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--integration">

### Integration

To start using the Quick actions feature, first load the `AIQuickActions` plugin in your editor configuration. [Learn more about installing and enabling AI features](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html).

Then, you can add the menu that opens the list of Quick actions (`'aiQuickActions'`)  to your main toolbar and/or balloon toolbar configurations. To learn more about toolbar configuration, refer to the [toolbar configuration](#ckeditor5/latest/getting-started/setup/toolbar.html) guide.

Finally, you can also add individual Quick actions to the toolbar as shortcuts for even easier access. For example, you can add the `'ask-ai'`  button, or the `'improve-writing'`  button (find it in the demo above). You can add whole categories to the toolbar, too. [Learn more about available actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html--default-actions).

The final example configuration looks as follows:

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIQuickActions, /* ... */ ],

        ai: {
            /* ... */
        },

        // Adding Quick action to the main editor toolbar.
        toolbar: [
            // The main Quick actions button
            'aiQuickActions',

            // Two individual actions
            'ask-ai',
            'improve-writing',

            // Whole action category
            'translate',

            /* ... */
        ],

        // Adding Quick Actions to the balloon toolbar. Since some of the actions are selection-sensitive,
        // accessing them might be easier for users using this kind of toolbar.
        balloonToolbar: {
            items: [
                // The main Quick actions button
                'aiQuickActions',

                // Two individual actions
                'ask-ai',
                'improve-writing',

                // Whole action category
                'translate',

                /* ... */
            ],
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--types-of-actions">

### Types of actions

There are two types of actions available in the Quick actions feature:

* Some actions, for instance, “Ask AI” or “Summarize”, lead to the [Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) interface with selected text added as context. The former will just open the Chat and allow you to start typing your message. The latter, however, will not only open the Chat but also start the conversation for your current editor selection right away, and expect a summary of that selection from the AI.
* Executing other actions like “Continue writing” or “Make shorter” will open the window interface conveniently right next to your selection and present the answers from the AI for you to accept or reject them.

You can define the behavior of each action when you [create custom ones](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html--custom-actions).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--default-actions">

### Default actions

By default, the Quick actions feature includes several built-in actions that speed up the content editing process. All Quick actions can be accessed through the menu button  (`'aiQuickActions'`) but also individually when handpicked by the integrator in the [editor toolbar configuration](#ckeditor5/latest/getting-started/setup/toolbar.html). You can add the whole action categories to the toolbar too.

Keep in mind that you can [add custom actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html--custom-actions) to the list and [remove defaults](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html--removing-default-actions).

Here’s the full list of available actions:

* `'ask-ai'`,
* “Chat commands” category (`'chat-commands'`)  
  * `'explain'`,
  * `'summarize'`,
  * `'highlight-key-points'`,
* `'improve-writing'`,
* `'continue'`,
* `'fix-grammar'`,
* “Adjust length” category (`'adjust-length'`)  
  * `'make-shorter'`,
  * `'make-longer'`,
* “Change tone” category (`'change-tone'`)  
  * `'make-tone-casual'`,
  * `'make-tone-direct'`,
  * `'make-tone-friendly'`,
  * `'make-tone-confident'`,
  * `'make-tone-professional'`,
* “Translate” category (`'translate'`)  
  * `'translate-to-english'`,
  * `'translate-to-chinese'`,
  * `'translate-to-french'`,
  * `'translate-to-german'`,
  * `'translate-to-italian'`,
  * `'translate-to-portuguese'`,
  * `'translate-to-russian'`

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--custom-actions">

### Custom actions

The [config.ai.quickActions.extraCommands](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActionsConfig.html#member-extraCommands) property allows you to add new commands to the AI Quick Actions feature. Below, you will find an example of three extra actions added to the user interface: two of them open the quick actions window, but the last one interacts with the Chat. Learn more about [types of actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html--types-of-actions).

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIQuickActions, /* ... */ ],

        ai: {
            quickActions: {
                extraCommands: [
                    {
                        id: 'add-quote-from-famous-person',
                        label: 'Add a quote from a famous person',
                        prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
                        type: 'action',
                        model: 'claude-4-sonnet'
                    },
                    {
                        id: 'summarize-in-bullet-points',
                        label: 'Summarize',
                        displayedPrompt: 'Summarize in 5 bullet points',
                        prompt: 'Summarize the selected text in 5 bullet points.',
                        type: 'chat'
                    },
                    {
                        id: 'include-more-sarcasm',
                        label: 'Rewrite adding more sarcasm',
                        prompt: 'Rewrite using a sarcastic tone.',
                        type: 'action',
                        model: 'claude-4-sonnet'
                    }

                    // ... More commands ...
                ],
            },

            /* ... */
        }
    } )
    .then( ... )
    .catch( ... );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--removing-default-actions">

### Removing default actions

The [config.ai.quickActions.removeCommands](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActionsConfig.html#member-removeCommands) property allows you to remove existing commands from the AI Quick Actions feature. Here’s an example that removes two actions (”Explain” and “Summarize”):

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIQuickActions, /* ... */ ],

        ai: {
            quickActions: {
                removeCommands: [
                    'explain',
                    'summarize',

                    // ... More commands to remove ...
                ]
            },

            /* ... */
        }
    } )
    .then( ... )
    .catch( ... );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--common-api">

### Common API

Quick Actions can be triggered programmatically – execute system actions or custom prompts from code.

| API                                                                                                              | Description                                                                              |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [AIActions#executeAction()](../../api/module%5Fai%5Faiactions%5Faiactions-AIActions.html#function-executeAction) | Execute a system action or a custom prompt on the current selection.                     |
| [AIActionDefinition](../../api/module%5Fai%5Faiactions%5Faiactions-AIActionDefinition.html)                      | Type defining the parameters for an AI action (system actionName or custom userMessage). |
| [AIActionsNames](../../api/module%5Fai%5Faiactions%5Faiactions-AIActionsNames.html)                              | Enum of available system action names.                                                   |

See the [programmatic usage guide](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--quick-actions) for details, examples, and a live demo.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-actions.html--rest-api">

#### REST API

Quick Actions are also available via the [Actions REST API](#cs/latest/guides/ckeditor-ai/actions.html) for use outside the editor. Use this to run stateless content transforms like fixing grammar, improving writing, or running custom prompts from your backend or frontend code. See the [programmatic documentation](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) for examples and the [full API reference](https://ai.cke-cs.com).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-chat.html"</a>

## AI Chat

The AI Chat is a conversational AI that can aid content creation and editing. It introduces a dynamic chat interface designed to facilitate rich, multi-turn interactions between users and AI, enabling an interactive and collaborative experience within writing workflows.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--demo">

### Demo

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--key-capabilities">

### Key capabilities

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--working-with-the-document">

#### Working with the document

CKEditor AI operates directly within the context of your document. When you chat with it, you can ask questions about specific sections, request a full-document proofreading, and more.

By enabling [Web search](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--web-search) or [Reasoning](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--reasoning), you can extend its capabilities — allowing the chat to look up information online and tackle complex tasks step by step.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--making-changes-to-the-content">

#### Making changes to the content

Not only can you chat with the AI, but you can also use it to introduce changes to your document. Ask it to _“Summarize the document”_, _“Turn this report into a one-page executive summary”_, or _“Suggest better section titles and subheadings”_. The AI will then propose a series of changes to the document you can [review](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--previewing-changes) and [accept or discard one by one](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--applying-changes). **Copying and pasting chat transcripts is over; CKEditor AI understands your content and edits with you hand in hand**.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--brainstorming">

#### Brainstorming

The chat feature jump-starts your creative process. Begin with a blank document and ask the AI for ideas. Build your content step by step by chatting and applying changes. Then review – or have the AI rewrite – the final draft for best results. All in one place.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--integration">

### Integration

To start using the Chat feature, load the `AIChat` plugin in your editor configuration. The Chat button  will appear in the AI user interface along with the Chat history . [Learn more about installing and enabling AI features](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--available-models">

### Available models

Users can select the desired AI model for their conversation from a dropdown at the bottom of the chat.

Once selected, the AI model will persist for the duration of the conversation. If you want to change the model, you can start a new conversation using a dedicated \+ New chat button at the top-right corner of the chat panel.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--web-search">

#### Web search

Web search in Chat allows it to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers. Toggle the “Enable web search” button  for a compatible model to start using the Web search functionality.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--reasoning">

#### Reasoning

Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching. Toggle the “Enable reasoning” button  for a compatible model to start using Reasoning.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--configuration">

#### Configuration

The optional [config.ai.models](../../api/module%5Fai%5Faiconfig-AIConfig.html#member-models) setting controls the models available to the users across all AI features (Chat and Review Mode). The property lets you set the default model, tailor the available models list, and control the model selector UI visibility. [Learn more about available AI models](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--supported-ai-models).

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIChat, AIEditorIntegration, /* ... */ ],

        ai: {
            models: {
                defaultModelId: 'claude-3-5-haiku',
                displayedModels: [ 'gpt', 'claude' ],
                showModelSelector: false
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--adding-context-to-conversations">

### Adding context to conversations

The AI chat can work with your document and beyond. Use the “Add context” button  on the right of the prompt input, to add URLs, files, and external resources to your conversation.

Ask the AI about specific resources, for instance, _“Describe the attached image”_ or _“Summarize the key points from the attached Word document”_. The AI will analyze those resources for you and provide information you can easily use in your document.

External resources enable you to seamlessly integrate knowledge bases and other centralized data into your AI Chat conversations. Instead of uploading documents each time you want to chat, you can simply select them from a list and reference them during your conversation. Learn more about [configuring resources](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--configuring-conversation-context) in AI Chat.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--configuring-conversation-context">

#### Configuring conversation context

The [config.ai.chat.context](../../api/module%5Fai%5Faichat%5Faichat-AIChatConfig.html#member-context) property configures the AI Chat menu for adding resources to the prompt context.

The example below enables built-in options to add the current [document](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-document), [URLs](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-urls), and [files](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-files) to the conversation context by the user.

It also demonstrates a [context sources configuration](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-sources) that introduces a menu with external resources fetched from a database or an external API for the user to pick from. You can learn more about the configuration of a [custom context providers](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIContextProvider.html) in the documentation.

See the example configuration below:

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIChat, AIEditorIntegration, /* ... */ ],

        ai: {
            chat: {
                context: {
                    // Allow for adding the current document to the conversation.
                    document: {
                        enabled: true
                    },

                    // Allow for adding URLs to the conversation.
                    urls: {
                        enabled: true
                    },

                    // Allow for uploading files to the conversation.
                    files: {
                        enabled: true
                    },

                    // External resources configuration.
                    sources: [
                        // Definition of the custom context provider.
                        {
                            // The unique identifier of the provider.
                            id: 'my-docs',

                            // The human-readable name of the provider.
                            label: 'My Documents',

                            // The async callback to retrieve the list of available resources.
                            // Usually involves fetching data from a database or an external API,
                            // but here we use a simple array of resources for demonstration purposes.
                            getResources: async ( query ) => [
                                // Text resources.
                                {
                                    id: 'text3',
                                    type: 'text',
                                    label: 'Internal note in HTML format',
                                    data: {
                                        content: '<h2>HTML note</h2><p>Lorem ipsum dolor sit amet...</p>',
                                        type: 'html'
                                    }
                                },
                                {
                                    id: 'text4',
                                    type: 'text',
                                    label: 'Internal note (fetched on demand)',

                                    // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below).
                                    // This will prevent fetching large content along with the list of resources.
                                },

                                // URLs to resources.
                                {
                                    id: 'url2',
                                    type: 'web-resource',
                                    label: 'Company brochure in PDF',
                                    data: 'https://example.com/brochure.pdf'
                                },
                                {
                                    id: 'url3',
                                    type: 'web-resource',
                                    label: 'Company website in HTML',
                                    data: 'https://example.com/index.html'
                                },

                                // ...
                            ],

                            // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback.
                            // When the user picks a specific resource,  the content will be fetched on demand (from database or external API) by this callback.
                            // This prevents fetching large resources along with the list of resources.
                            getData: ( id ) => fetchDocumentContent( id )
                        },

                        // More context providers...
                    ]
                },
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--automatically-add-selection-to-context">

#### Automatically add selection to context

By default, the editor selection is added to the AI Chat context only when the user explicitly clicks the “Ask AI” button. You can change this behavior by enabling the [config.ai.chat.context.alwaysAddSelection](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-alwaysAddSelection) option. When set to `true`, the current editor selection is automatically added to the conversation context whenever the user changes their selection. If the selection becomes collapsed (empty), it is automatically removed from the context.

This option requires the [document](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-document) context to be enabled (which is the default).

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        /* ... */

        plugins: [ AIChat, AIEditorIntegration, /* ... */ ],

        ai: {
            chat: {
                context: {
                    alwaysAddSelection: true
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--adding-context-via-custom-context-provider">

#### Adding context via custom context provider

It’s also possible to allow for adding the context using a custom external UI, for example, a file manager.

First, using the [config.ai.chat.context.customItems](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContextConfig.html#member-customItems) configuration option, add a button to the “Add context” dropdown that upon pressing will execute the configured [callback](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIContextCustomItem.html#member-callback) (for example, open custom content manager). Then you can use the [AIChatContext class API](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContext.html) to attach the resource chosen by the user to the conversation context. There are various API methods to use depending on the context type. See an example code below.

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIChat, AIEditorIntegration, /* ... */ ],

        ai: {
            chat: {
                context: {
                    // Other configuration options...
                    customItems: [
                        {
                            id: 'open-file-manager', // Unique item ID.
                            label: 'Open file manager', // Button label displayed in the dropdown.
                            icon: IconImage, // Icon displayed next to the label.
                            callback: ( editor: Editor ) => {
                                // `openFileManager()` is provided by you. It opens a custom UI, and returns a promise.
                                // After the user finishes choosing files, the `openFileManager()` promise resolves with data of these files.
                                openFileManager().then( chosenFiles => {
                                    editor.plugins.get( 'AIChatController' ).activeConversation.chatContext.addFilesToContext( chosenFiles );
                                } );
                            }
                        },
                        {
                            id: 'open-url-manager', // Unique item ID.
                            label: 'Open URL manager', // Button label displayed in the dropdown.
                            icon: IconURL, // Icon displayed next to the label.
                            callback: ( editor: Editor ) => {
                                // `openURLManager()` is provided by you. It opens a custom UI, and returns a promise.
                                // After the user finishes choosing a URL, the `openURLManager()` promise resolves with proper data.
                                openURLManager().then( chosenURL => {
                                    editor.plugins.get( 'AIChatController' ).activeConversation.chatContext.addURLToContext( chosenURL );
                                } );
                            }
                        }
                    ]
                },
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--welcome-message">

### Welcome message

The AI Chat feature allows you to customize the welcome message displayed to users when the chat initializes. You can set the [config.ai.chat.welcomeMessage](../../api/module%5Fai%5Faichat%5Faichat-AIChatConfig.html#member-welcomeMessage) option in your editor configuration to provide a custom message. If this option is not set, a default welcome message will be shown.

```
ClassicEditor.create( {
    /* ... */

    plugins: [ AIChat, AIEditorIntegration, /* ... */ ],

    ai: {
        chat: {
            welcomeMessage: 'Hello! How can I assist you today?'

            // More configuration options...
        }
    }
} )
.then( /* ... */ )
.catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--working-with-ai-generated-changes">

### Working with AI-generated changes

If you ask the AI for changes to your document, for instance, _“Bold key facts in the document”_, you will receive a series of proposed changes instead of plain text responses:

Move your cursor over any change to highlight the section of your document it applies to, helping you identify it among other proposed edits.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--showing-details">

#### Showing details

You can toggle details of the changes by pressing the “Show details”  button. By default, you will see detailed information on what exactly was suggested, including additions (green markers), removals (red markers), and formatting changes (blue markers).

Click the button again to see a clean, simplified overview of the changes as they’ll appear in your document once accepted.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--previewing-changes">

#### Previewing changes

Click on the item in the list to display the information window about an individual change with options to [apply it](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--applying-changes), [turn it into a Track Changes suggestion](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--inserting-track-changes-suggestions), or [reject it](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--rejecting-suggestions). You can use this window to browse all proposed changes and work with them one by one. As you navigate through the changes, the window will automatically follow the corresponding sections of the document.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--applying-changes">

#### Applying changes

Each suggestion on the list comes with an “Apply” button  that allows you to apply the change to the document immediately.

Click the “Apply all” button in chat to apply all AI suggestions at once.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--inserting-track-changes-suggestions">

#### Inserting Track Changes suggestions

[When Track Changes feature is available in your integration](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--track-changes-dependency), the “Add as suggestion” button  will be available in chat. Clicking it will create a Track Changes suggestion that can later be reviewed or discarded.

You can pick the “Suggest all” option under the list to turn all changes suggested by AI into Track Changes suggestions.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--rejecting-suggestions">

#### Rejecting suggestions

You can click the “Reject change” button  to reject AI suggestions you do not want before applying the remaining ones or turning them into Track Changes suggestions.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--chat-history">

### Chat history

All your past conversations appear in the Chat history . Click the button to open the list, where you can reopen, rename, or delete any conversation.

Conversations are grouped by date to help you navigate your project easily. You can filter conversations by name using the search field at the top of the user interface.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--chat-shortcuts">

### Chat Shortcuts

The AI Chat feature can be enhanced by AI Chat Shortcuts – customizable actions that help users trigger common or useful prompts with a single click. These shortcuts appear at the start of a new conversation, making it faster for users to ask questions, request summaries, check grammar, and more.

AI Chat Shortcuts require loading the [AIChatShortcuts](../../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcuts.html) plugin in your editor configuration.

You can configure which shortcuts are available using the [config.ai.chat.shortcuts](../../api/module%5Fai%5Faichat%5Faichat-AIChatConfig.html#member-shortcuts) option. This allows you to define shortcut labels, icons, prompts, and the type of action to execute. Shortcuts streamline repetitive queries and encourage best practices in your writing workflows.

Example configuration:

```
import {
    AIChat,
    AIChatShortcuts,
    AIEditorIntegration,

    /* ... */
} from 'ckeditor5-premium-features';

ClassicEditor.create( {
    /* ... */

    // Adding the AIChatShortcuts plugin to enable the feature.
    plugins: [ AIChat, AIChatShortcuts, AIEditorIntegration, /* ... */ ],

    /* ... */

    ai: {
        chat: {
            shortcuts: [
                // This shortcut runs an AI Chat prompt with Reasoning and
                // Web Search features turned on.
                {
                    id: 'continue-writing',
                    type: 'chat',
                    label: 'Continue writing',
                    prompt: 'Continue writing this document. Match the existing tone, vocabulary level, and formatting. ' +
                        'Do not repeat or summarize earlier sections. Ensure logical flow and progression of ideas. ' +
                        'Add approximately 3 paragraphs.',
                    useReasoning: true,
                    useWebSearch: true
                },

                // This shortcut starts proofreading the document by the AI Review feature.
                {
                    id: 'fix-grammar-and-spelling',
                    type: 'review',
                    label: 'Fix grammar and spelling',
                    commandId: 'correctness'
                },

                // This shortcut switches the UI to the Translate feature and allows
                // the user decide what to do next (choose a language).
                {
                    id: 'translate-document',
                    type: 'translate',
                    label: 'Translate document'
                }
            ]
        }
    }
} )
.then( /* ... */ )
.catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--common-api">

### Common API

AI Chat can be controlled programmatically – send messages, start conversations, and manage chat context from code.

| API                                                                                                                                                        | Description                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [AIChatController#sendMessage()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-sendMessage)                             | Programmatically send a message to AI Chat.                          |
| [AIChatController#startConversation()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-startConversation)                 | Start a new chat conversation.                                       |
| [AIChatController#addSelectionToChatContext()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-addSelectionToChatContext) | Attach the current editor selection as context for the next message. |

See the [programmatic usage guide](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--chat) for details, examples, and a live demo.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-chat.html--rest-api">

#### REST API

AI Chat conversations are also available via the [Conversations REST API](#cs/latest/guides/ckeditor-ai/conversations.html), which supports multi-turn conversation history, file uploads, and web search capabilities. Use this to build chat-based AI features outside the editor. See the [programmatic documentation](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) for examples and the [full API reference](https://ai.cke-cs.com).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-deployment.html"</a>

## Deployment options

CKEditor AI backend is available in two deployment modes: **Cloud (SaaS)** and **On-premises**. Both options provide the same core AI features – [Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html), [Quick Actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html), [Review](#ckeditor5/latest/features/ai/ckeditor-ai-review.html), and [Translate](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html) – with the on-premises version offering additional capabilities such as custom AI models and [MCP support](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--cloud-saas">

### Cloud (SaaS)

The Cloud (SaaS) deployment offers the fastest way to get started with CKEditor AI. The AI service is hosted and managed by CKEditor, so there is no server-side setup required on your end. You only need to provide a valid license key and configure the editor-side plugins as described in the [integration guide](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html).

For more information about the Cloud AI service, refer to the [CKEditor AI Cloud Services documentation](#cs/latest/guides/ckeditor-ai/overview.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--on-premises">

### On-premises

The on-premises deployment allows you to run the CKEditor AI service on your own infrastructure, including private cloud environments. The service is distributed as Docker images compatible with standard container runtimes.

On-premises deployment gives you full control over the AI service, including the ability to use custom AI models and providers, and to extend CKEditor AI with custom tools via [MCP (Model Context Protocol)](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html).

For detailed setup instructions, requirements, and configuration, refer to the [CKEditor AI On-Premises documentation](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--connecting-the-editor-to-an-on-premises-service">

#### Connecting the editor to an on-premises service

To point the editor to your on-premises AI service, set the [config.ai.serviceUrl](../../api/module%5Fai%5Faiconfig-AIConfig.html#member-serviceUrl) property to the URL of your on-premises instance:

```
ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',

        ai: {
            serviceUrl: 'https://your-on-prem-host.com/v1',

            // ... Other AI configuration options.
        }

        // ... Other editor configuration.
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--custom-ai-models">

#### Custom AI models

The on-premises version supports custom AI model providers, allowing you to use your own models hosted on services like Google Cloud, Microsoft Azure, or self-hosted solutions. Models configured on the server side will automatically appear in the editor’s model selector.

For configuration details, refer to the [on-premises configuration guide](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--custom-models).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--mcp-support">

#### MCP support

The on-premises deployment supports the Model Context Protocol (MCP), which allows you to extend CKEditor AI with custom external tools. Learn more in the [MCP support](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html) guide.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-deployment.html--feature-comparison">

### Feature comparison

| Feature                                                           | Cloud (SaaS) | On-premises |
| ----------------------------------------------------------------- | ------------ | ----------- |
| Hosted and managed by CKEditor                                    | ✅ Yes        | ❌ No        |
| Custom infrastructure                                             | ❌ No         | ✅ Yes       |
| Custom AI models and providers                                    | ❌ No         | ✅ Yes       |
| [MCP support](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html) | ❌ No         | ✅ Yes       |

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-integration.html"</a>

## Integrating CKEditor AI with your application

This guide will take you step-by-step through the process of running CKEditor AI in your editor integration. It also presents possible configuration and customization options.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and provide [essential configuration](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--sample-implementation):

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--enabling-individual-features">

#### Enabling individual features

Each AI feature is a standalone plugin that you can include or exclude from the `plugins` array depending on your needs. For example, to use only AI Review and AI Translate without Chat or Quick Actions:

```
import { ClassicEditor } from 'ckeditor5';
import { AIReviewMode, AITranslate, AIEditorIntegration, TrackChanges } from 'ckeditor5-premium-features';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',

        plugins: [
            AIReviewMode, AITranslate, AIEditorIntegration, TrackChanges,
            /* ... */
        ],

        ai: {
            container: {
                /* ... */
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The following table lists the plugins responsible for each feature:

| Feature           | Plugin          | Description                                   |
| ----------------- | --------------- | --------------------------------------------- |
| AI Chat           | AIChat          | Conversational AI assistant                   |
| AI Chat Shortcuts | AIChatShortcuts | Predefined shortcuts displayed in the AI Chat |
| AI Quick Actions  | AIQuickActions  | One-click AI-powered content transformations  |
| AI Review         | AIReviewMode    | AI-powered quality assurance checks           |
| AI Translate      | AITranslate     | AI-powered document translation               |

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--sample-implementation">

### Sample implementation

An example CKEditor AI configuration is presented below. You can learn more about specific configurations such as [UI types and positioning](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--ui-types-and-positioning) or [Track Changes dependency](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--track-changes-dependency) in the later sections of this guide.

To learn more about toolbar configuration, refer to the [toolbar configuration](#ckeditor5/latest/getting-started/setup/toolbar.html) guide.

```
// Simplified integration of the Users plugin needed for TrackChanges integration.
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Users' ];
    }

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Just add a minimal dummy user
        users.addUser( { id: 'user-1', name: 'John Doe' } );
        users.defineMe( 'user-1' );
    }
}

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',

        plugins: [ AIChat, AIQuickActions, AIReviewMode, AITranslate, AIEditorIntegration, AIChatShortcuts, TrackChanges, UsersIntegration, /* ... */ ],

        // Extend the main editor toolbar configuration with additional buttons:
        // - 'aiQuickActions': opens the AI Quick Actions menu,
        // - 'ask-ai': moves the user focus to the AI Chat,
        // - 'improve-writing': executes the "Improve Writing" quick action.
        //
        // You can add more AI Quick actions to the toolbar configuration if needed.
        toolbar: [ 'aiQuickActions', 'ask-ai', 'improve-writing', /* ... */ ],

        // You can use the same AI feature buttons in the balloon toolbar configuration for contextual convenience.
        balloonToolbar: {
            items: [
                /* ... */

                'aiQuickActions', 'ask-ai', 'improve-writing', /* ... */
            ]
        },

        // Configure the document identifier for AI chat history and context preservation.
        // This should be a unique identifier for the document/article being edited.
        collaboration: {
            channelId: 'channelId' // Replace with your actual document ID
        },

        // Main configuration of AI feature.
        ai: {
            // ⚠️ Mandatory UI configuration.
            // Display the AI user interface in a dedicated DOM element. The interface can be also displayed
            // in an overlay or in a custom way, learn more in the next chapters of this guide.
            container: {
                type: 'sidebar',
                element: document.querySelector( '.ai-sidebar' ),

                // (Optional) Whether the AI interface should be visible when the editor is created.
                visibleByDefault: false
            },

            // (Optional) Configure the AI Chat feature by configuring available context resources.
            chat: {
                // (Optional) Configure AI Chat Shortcuts that appear at the start of a new conversation.
                shortcuts: [
                    {
                        id: 'continue-writing',
                        type: 'chat',
                        label: 'Continue writing',
                        prompt: 'Continue writing this document. Match the existing tone, vocabulary level, and formatting. ' +
                            'Do not repeat or summarize earlier sections. Ensure logical flow and progression of ideas. ' +
                            'Add approximately 3 paragraphs.'
                    }
                ],

                context: {
                    // Configuration of the built-in context options.
                    document: {
                        enabled: true
                    },
                    urls: {
                        enabled: false
                    },
                    files: {
                        enabled: true
                    },

                    // (Optional) Additional sources for the AI Chat context.
                    sources: [
                        // Definition of the custom context provider.
                        {
                            // The unique identifier of the provider.
                            id: 'my-docs',

                            // The human-readable name of the provider.
                            label: 'My Documents',

                            // The async callback to retrieve the list of available resources.
                            // Usually involves fetching data from a database or an external API,
                            // but here we use a simple array of resources for demonstration purposes.
                            getResources: async ( query ) => [
                                // Texts in various formats
                                {
                                    id: 'text1',
                                    type: 'text',
                                    label: 'Internal note in plain text format',
                                    data: {
                                        content: 'Lorem ipsum dolor sit amet...',
                                        type: 'text'
                                    }
                                },
                                {
                                    id: 'text2',
                                    type: 'text',
                                    label: 'Internal note in Markdown format',
                                    data: {
                                        content: '## Markdown note\n\n**Lorem ipsum** dolor sit amet...',
                                        type: 'markdown'
                                    }
                                },
                                {
                                    id: 'text3',
                                    type: 'text',
                                    label: 'Internal note in HTML format',
                                    data: {
                                        content: '<h2>HTML note</h2><p>Lorem ipsum dolor sit amet...</p>',
                                        type: 'html'
                                    }
                                },
                                {
                                    id: 'text4',
                                    type: 'text',
                                    label: 'Internal note (fetched on demand)',

                                    // Note: Since the `data` property is not provided, the content will be retrieved using the `getData()` callback (see below).
                                    // This will prevent fetching large content along with the list of resources.
                                },

                                // URLs to resources in different formats
                                {
                                    id: 'url1',
                                    type: 'web-resource',
                                    label: 'Blog post in Markdown',
                                    data: 'https://example.com/blog-post.md'
                                },
                                {
                                    id: 'url2',
                                    type: 'web-resource',
                                    label: 'Company brochure in PDF',
                                    data: 'https://example.com/brochure.pdf'
                                },
                                {
                                    id: 'url3',
                                    type: 'web-resource',
                                    label: 'Company website in HTML',
                                    data: 'https://example.com/index.html'
                                },
                                {
                                    id: 'url4',
                                    type: 'web-resource',
                                    label: 'Terms of service in plain text',
                                    data: 'https://example.com/terms-of-service.txt'
                                },

                                // ...
                            ],

                            // The optional callback to retrieve the content of resources without the `data` property provided by the `getResources()` callback.
                            // When the user picks a specific resource,  the content will be fetched on demand (from database or external API) by this callback.
                            // This prevents fetching large resources along with the list of resources.
                            getData: ( id ) => fetchDocumentContent( id )
                        },

                        // More context providers...
                    ]
                }
            },

            // (Optional) The configuration for AI models used across all AI features (Chat and Review Mode).
            models: {
                defaultModelId: 'gpt-5',
                displayedModels: [ 'gpt', 'claude' ],
                showModelSelector: true
            },

            // (Optional) Configure the AI Quick Actions feature by adding a new command.
            quickActions: {
                extraCommands: [
                    // An action that opens the AI Chat interface for interactive conversations.
                    {
                        id: 'explain-like-i-am-five',
                        displayedPrompt: 'Explain like I am five',
                        prompt: 'Explain the following text like I am five years old.',
                        type: 'CHAT'
                    },

                    // ... More custom actions ...
                ],
            },
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--supported-ai-models">

#### Supported AI models

CKEditor AI supports OpenAI, Anthropic, and Gemini AI models. By default, the automatically selected model will be used for optimal cost and performance.

You can configure the list of available models and the default model using the unified [model configuration](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--configuration), which applies to all AI features (Chat and Review Mode).

Here’s a detailed list of available models with their capabilities:

| **Model**             | **Description**                                                                            | [Web Search](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--web-search) | [Reasoning](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--reasoning) | [Configuration id](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--configuration)                                                      |
| --------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto (default)**    | Automatically selects best model for speed, quality, and cost.                             | Yes                                                                           | Yes                                                                         | 'auto' (also 'agent-1', learn more about [compatibility versions](#cs/latest/guides/ckeditor-ai/models.html--model-compatibility-versions)) |
| **GPT-5.4**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks              | Yes                                                                           | Yes                                                                         | 'gpt-5.4'                                                                                                                                   |
| **GPT-5.2**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks              | Yes                                                                           | Yes                                                                         | 'gpt-5.2'                                                                                                                                   |
| **GPT-5.1**           | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks              | Yes                                                                           | Yes                                                                         | 'gpt-5.1'                                                                                                                                   |
| **GPT-5**             | OpenAI’s flagship model for advanced reasoning, creativity, and complex tasks              | Yes                                                                           | Yes                                                                         | 'gpt-5'                                                                                                                                     |
| **GPT-5 Mini**        | A lightweight version of GPT-5 – faster, more cost-efficient                               | Yes                                                                           | Yes                                                                         | 'gpt-5-mini'                                                                                                                                |
| **Claude 4.6 Sonnet** | Advanced model with improved creativity, reliability, and reasoning                        | Yes                                                                           | Yes                                                                         | 'claude-4-6-sonnet'                                                                                                                         |
| **Claude 4.5 Haiku**  | Cost-efficient model for quick interactions with improved reasoning                        | Yes                                                                           | Yes                                                                         | 'claude-4-5-haiku'                                                                                                                          |
| **Claude 4.5 Sonnet** | Advanced model with improved creativity, reliability, and reasoning                        | Yes                                                                           | Yes                                                                         | 'claude-4-5-sonnet'                                                                                                                         |
| **Gemini 3.1 Pro**    | Google’s advanced model for versatile problem-solving and research                         | Yes                                                                           | Yes                                                                         | 'gemini-3-1-pro'                                                                                                                            |
| **Gemini 3 Flash**    | Lightweight Gemini model for fast, cost-efficient interactions                             | Yes                                                                           | Yes                                                                         | 'gemini-3-flash'                                                                                                                            |
| **Gemini 2.5 Flash**  | Lightweight Gemini model for fast, cost-efficient interactions                             | Yes                                                                           | Yes                                                                         | 'gemini-2-5-flash'                                                                                                                          |
| **GPT-4.1**           | OpenAI’s model for reliable reasoning, speed, and versatility                              | Yes                                                                           | No                                                                          | 'gpt-4.1'                                                                                                                                   |
| **GPT-4.1 Mini**      | A lighter variant of GPT-4.1 that balances speed and cost while maintaining solid accuracy | Yes                                                                           | No                                                                          | 'gpt-4.1-mini'                                                                                                                              |

We intend to expand this list of supported agents further with time. The [on-premises version](#ckeditor5/latest/features/ai/ckeditor-ai-deployment.html) also supports custom models and your own API keys. [Share your feedback on model availability](https://ckeditor.com/contact/).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--cloud-version-endpoint">

#### Cloud version endpoint

While using the cloud version of the CKEditor AI feature, you need to provide the service endpoint.

```
ai: {
    serviceUrl: 'https://ai.cke-cs.com/v1'
}

```

If you are using the EU cloud region, remember to adjust the endpoint:

```
ai: {
    serviceUrl: 'https://ai.cke-cs-eu.com/v1'
}

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--document-id">

#### Document ID

The [config.collaboration.channelId](../../api/module%5Fcollaboration-core%5Fconfig-RealTimeCollaborationConfig.html#member-channelId) configuration serves as the document identifier corresponding to the edited resource (article, document, etc.) in your application. This ID is essential for maintaining [Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) history, ensuring that AI conversations are properly associated with the specific document being edited. When users interact with AI features, their chat history is preserved and linked to this document ID.

```
ClassicEditor
    .create( {
        /* ... */

        collaboration: {
            channelId: 'DOCUMENT_ID'
        },

        /* ... */
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--track-changes-dependency">

#### Track Changes dependency

CKEditor AI can leverage the TrackChanges plugin to enhance the user experience, for instance, by allowing users to turn AI-generated content into suggestions that can later be reviewed, accepted, or rejected. Without the TrackChanges plugin, the CKEditor AI will work, but some functionalities may be limited. For the most complete integration, we highly recommend using TrackChanges along with CKEditor AI.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--ui-types-and-positioning">

#### UI types and positioning

CKEditor AI gives you flexible options for displaying the AI user interface. The [config.ai.container](../../api/module%5Fai%5Faiconfig-AIConfig.html#member-container) property allows you to choose from three different UI placement modes:

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--sidebar">

##### Sidebar

When in [AIContainerSidebar](../../api/module%5Fai%5Faiconfig-AIContainerSidebar.html) mode, the AI user interface is displayed in a specific DOM element, allowing you to inject it into your existing user interface.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...

        ai: {
            container: {
                type: 'sidebar',

                // Existing DOM element to use as the container for the AI user interface.
                element: document.querySelector( '#ai-sidebar-container' )

                // (Optional) The preferred side for positioning the tab buttons.
                side: 'right'
            },
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

In addition to the above, we recommend using the following or similar CSS to style the sidebar container for the AI user interface (tabs) to render optimally:

```
#ai-sidebar-container .ck.ck-ai-tabs {
    /* An arbitrary fixed width to limit the space consumed by the AI tabs. */
    width: 500px;

    /* A fixed height that enables vertical scrolling (e.g., in the AI Chat feed). */
    height: 800px;
}

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--overlay">

##### Overlay

When in [AIContainerOverlay](../../api/module%5Fai%5Faiconfig-AIContainerOverlay.html) mode, the AI user interface is displayed on top of the page, allowing you to position it on your preferred side. This mode is best suited for integrations with limited space.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...

        ai: {
            container: {
                type: 'overlay',
                side: 'right'
            },
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Learn how to [toggle the AI overlay](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--toggling-the-ui) using a dedicated toolbar button.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--custom">

##### Custom

When in [AIContainerCustom](../../api/module%5Fai%5Faiconfig-AIContainerCustom.html) mode, the AI user interface is displayed in a custom way, allowing you to use the building blocks of the AI user interface to create your own and satisfy the specific needs of your application.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...

        ai: {
            container: {
                type: 'custom'
            },
        }
    } )
    // A custom integration of the AI user interface placing the tab buttons and panels separately in custom containers.
    .then( editor => {
        const tabsPlugin = editor.plugins.get( 'AITabs' );

        for ( const id of tabsPlugin.view.getTabIds() ) {
            const tab = tabsPlugin.view.getTab( id );

            // Display tab button and panel in a custom container.
            myButtonsContainer.appendChild( tab.button.element );
            myPanelContainer.appendChild( tab.panel.element );
        }
    } )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--toggling-the-ui">

#### Toggling the UI

The user interface can be easily toggled by the users using the `'toggleAi'`  toolbar button. The button becomes available for configuration when the [AIEditorIntegration](../../api/module%5Fai%5Faieditorintegration%5Faieditorintegration-AIEditorIntegration.html) plugin is enabled.

The following example shows how to enable the `'toggleAi'` button in the main editor toolbar:

```
import { ClassicEditor } from 'ckeditor5';
import { /* ... */, AIEditorIntegration } from 'ckeditor5-premium-features';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ AIEditorIntegration, /* ... */ ],

        // Enable the `'toggleAi'` button in the main editor toolbar.
        toolbar: [ 'toggleAi', /* ... */ ],

        ai: {
            container: {
                // ...
            },

            /* ... */
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If you wish to initially hide the overlay until a user opens it with a button, you can use the [dedicated configuration](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--hiding-the-ui-on-initialization).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--hiding-the-ui-on-initialization">

#### Hiding the UI on initialization

By default, the AI interface will be visible when the editor is created (and the [related toolbar button](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--toggling-the-ui) will be active). If you wish to have it hidden until the user opens it (e.g. via toolbar button), set [config.ai.container.visibleByDefault](../../api/module%5Fai%5Faiconfig-AIConfig.html#member-container) property to `false`.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--maximizing-the-ui">

#### Maximizing the UI

The maximize button  in the upper-right corner allows changing the width of the CKEditor AI user interface. Users can use this button to interact with the AI features more comfortably, especially while [chatting](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) and interacting with large chunks of content.

Clicking this button will toggle the `.ck-ai-tabs_maximized` CSS class on the `.ck-ai-tabs` DOM element. The integrator can then style the geometry of the element based on the specific requirements of the integration.

* When the UI is configured in the [sidebar mode](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--sidebar), the decision on how to style the maximized state of the user interface is left to the integrator due to many possible integration types and configurations.
* When the UI is configured in the [overlay mode](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--overlay), integrators can override the `--ck-ai-tabs-overlay-width-maximized` CSS custom property to change the width of the overlay.

```
:root {
    /* The CKEditor AI interface will consume 40% of the space when maximized */
    --ck-ai-tabs-overlay-width-maximized: 40%;
}

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--permissions">

#### Permissions

Learn more about the permissions system used in CKEditor AI in a [dedicated guide](#cs/latest/guides/ckeditor-ai/permissions.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--chat">

### Chat

Learn more about integrating the Chat feature  in a [dedicated guide](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--quick-actions">

### Quick Actions

Learn more about integrating the Quick Actions feature  in a [dedicated guide](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--review">

### Review

Learn more about integrating the Review feature  in a [dedicated guide](#ckeditor5/latest/features/ai/ckeditor-ai-review.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-integration.html--translate">

### Translate

Learn more about integrating the Translate feature  in a [dedicated guide](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-mcp.html"</a>

## MCP support

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard for connecting AI models to external tools and data sources. CKEditor AI supports MCP, letting you extend its capabilities with custom tools – such as searching knowledge bases, querying databases, integrating with third-party services, or even providing your own custom AI tools – all accessible directly from the [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--overview">

### Overview

When MCP servers are connected to the on-premises AI service, the AI model can use MCP tools during conversations. The general flow is:

1. The user sends a message in the AI Chat.
2. The AI model may decide to call an MCP tool based on the message and conversation context.
3. The on-premises AI service invokes the tool on the connected MCP server.
4. The tool result is returned to the AI service and may be used to improve the quality and accuracy of the response.
5. The tool result is also sent to the editor, where it can be processed and displayed.

You can connect both third-party MCP tools (such as public knowledge-base or database connectors) and your own custom tools. For third-party tools, the integration may be as simple as registering a callback to display their results. For custom tools, you have full control over what data the tool returns and how it is presented in the editor.

As an integrator, you can:

* Use MCP tools to **return additional data** for the main AI service agent, to make it aware of the knowledge specific to your application.
* **Handle tool responses** by registering callbacks that process tool notifications and results, to provide a customized rich user experience specific to your use cases.
* **Pass context** to MCP tools alongside user messages, to give your custom tools more input to operate on, beyond the user prompt.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--server-side-configuration">

### Server-side configuration

MCP servers are configured on the on-premises AI service, not in the CKEditor 5 editor configuration. For server setup, connection options, and other details, refer to the [on-premises MCP configuration guide](#cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--client-side-integration">

### Client-side integration

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--handling-mcp-tool-responses">

#### Handling MCP tool responses

When an MCP tool is called, progress notifications and the final result are passed to the editor. Use [registerToolDataCallback()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-registerToolDataCallback) to process this data and control how it appears in the AI Chat.

```
const aiChatController = editor.plugins.get( 'AIChatController' );

aiChatController.registerToolDataCallback( ( toolData, api ) => {
    // Handle tool data here.
} );

```

Each callback receives:

* `toolData` ([AIToolData](../../api/module%5Fai%5Faicore%5Fmodel%5Faiinteraction-AIToolData.html)) – the tool name, event type, and data payload. The MCP tool is fully responsible for the contents of `toolData.data`.
* `api` ([AIChatFeedAPI](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatFeedAPI.html)) – methods for manipulating the chat feed.

Use `toolData.type` (`'result'` or `'notification'`) and `toolData.toolName` to route handling logic. Tool names are prefixed with the server name in the format `{serverName}-{toolName}` (for example, `my-server-search-docs`).

You can register multiple callbacks to handle different tools separately.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--handling-tool-notifications">

##### Handling tool notifications

Tools may send notifications or progress updates, informing about the current state of the call, or sharing additional insight about what the tool does.

For these kinds of updates, `toolData.type` will be set to `'notification'`.

You can use this data to show a custom loading message or even provide your own “chain-of-thought” component.

```
const aiChatController = editor.plugins.get( 'AIChatController' );

aiChatController.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'notification' ) {
        api.setLoadingMessage( toolData.data.message );
    }
} );

```

Note that tool notifications are treated as temporary data and **are not** saved in the conversation history. They will not be shown when a conversation is loaded from the history.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--handling-tool-results">

##### Handling tool results

Every tool is expected to return a result after it finishes processing.

Tool result data has `toolData.type` set to `'result'`.

Tool results are displayed in the chat feed in the order they arrive. If a tool result comes before the AI’s proposed changes to the document, it will appear before them. If it arrives after, it will appear after. Tool results will never split the proposed changes.

Depending on your use case, you may simply show the result as text, or provide a custom, rich UI component that will display the returned data as a graph, table, or in any custom way that fits your needs.

Unlike the temporary updates from notifications, results are persistent data saved in the conversation history. The data is saved as-received. When a conversation is loaded from history, the same registered callbacks will be used to handle the saved tool data.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--displaying-tool-results-as-text">

###### Displaying tool results as text

Use the provided API to insert the text result into the chat feed:

```
const aiChatController = editor.plugins.get( 'AIChatController' );

aiChatController.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'result' ) {
        api.insertTextReply( toolData.data.summary );
    }
} );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--building-custom-ui-from-structured-data">

###### Building custom UI from structured data

When a tool returns structured data (for example, tabular data as JSON), you can build custom HTML and insert it into the chat feed:

```
const aiChatController = editor.plugins.get( 'AIChatController' );

aiChatController.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'result' && toolData.data.rows ) {
        const headers = toolData.data.columns;
        const rows = toolData.data.rows;

        const headerHtml = headers.map( h => `<th>${ h }</th>` ).join( '' );
        const rowsHtml = rows.map( row =>
            '<tr>' + row.map( cell => `<td>${ cell }</td>` ).join( '' ) + '</tr>'
        ).join( '' );

        const tableHtml = `<table><thead><tr>${ headerHtml }</tr></thead><tbody>${ rowsHtml }</tbody></table>`;

        api.insertCustomElement( tableHtml );
    }
} );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--passing-context-to-mcp-tools">

#### Passing context to MCP tools

MCP tools automatically receive the conversation context when a user sends a message. However, your application often holds additional information that can help the tool produce better results. You can attach this data to messages so that MCP tools can use it.

There are two approaches: **message attributes** and **tool context items**. The key difference is in how they are used:

* **Message attributes** are metadata that is always present with the message and typically invisible to the end user. They are set programmatically and intended for data that should accompany every message transparently – for example, the user’s tenant ID, department, or session information.
* **Tool context items** are reflected in the UI as context pills next to the prompt input (similar to attached files or URLs). They are visible to the user, who can interact with them – add, review, or remove them. Use them for data that the user should be aware of, such as a search category, a customer name, or a content tag.

Both attributes and context items are saved in the conversation history.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--message-attributes">

##### Message attributes

Use the `attributes` parameter of [sendMessage()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-sendMessage) to attach metadata to a message. Attributes are forwarded to all connected MCP servers automatically.

```
const aiChatController = editor.plugins.get( 'AIChatController' );

await aiChatController.sendMessage( {
    message: 'Find related documents about this project',
    attributes: {
        department: 'engineering',
        projectId: 'proj-123'
    }
} );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--tool-context-items-advanced">

##### Tool context items (advanced)

Use [addToolItemToContext()](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContext.html#function-addToolItemToContext) to add context items that are displayed as pills in the chat UI and routed to a specific MCP server or tool. This is useful for scoping information like a search category, customer name, or content tag that the user should see and can interact with.

```
const aiChatController = editor.plugins.get( 'AIChatController' );
const conversation = aiChatController.activeConversation;

conversation.context.addToolItemToContext( {
    type: 'mcp-tool-context',
    mcpServerName: 'my-server',
    toolName: 'search-docs', // Optional. Omit to send context to all tools on the server.
    data: {
        category: 'compliance',
        region: 'EMEA'
    },
    id: 'search-scope-1' // Optional, 1-21 characters. Auto-generated if omitted.
} );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--common-api">

### Common API

The following APIs are used when integrating MCP tools with the editor:

* [AIChatController#registerToolDataCallback()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-registerToolDataCallback) – registers a callback to handle data from MCP tools (results and notifications).
* [AIChatController#sendMessage()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-sendMessage) – sends a message programmatically, with optional `attributes` forwarded to MCP servers.
* [AIChatContext#addToolItemToContext()](../../api/module%5Fai%5Faichat%5Fmodel%5Faichatcontext-AIChatContext.html#function-addToolItemToContext) – adds a context item targeted at a specific MCP server or tool.
* [AIChatFeedAPI](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatFeedAPI.html) – methods available inside tool data callbacks for manipulating the chat feed (`insertTextReply`, `insertCustomElement`, `setLoadingMessage`, `clearLoadingMessage`).
* [AIToolData](../../api/module%5Fai%5Faicore%5Fmodel%5Faiinteraction-AIToolData.html) – the data object passed to tool data callbacks, containing `toolName`, `type`, `data`, and `attributes`.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-mcp.html--related-resources">

### Related resources

* [Deployment options](#ckeditor5/latest/features/ai/ckeditor-ai-deployment.html) – learn about Cloud and On-premises deployment modes.
* [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) – learn about the AI Chat feature.
* [Integration guide](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html) – learn how to set up CKEditor AI in your application.
* [On-premises documentation](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html) – server-side setup and configuration.
* [REST API documentation](https://ai.cke-cs.com/v1/docs) – API reference for the AI service.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-overview.html"</a>

## CKEditor AI

By integrating AI writing assistance directly into the editing experience, CKEditor AI empowers authors with real-time AI writing support, streamlines content creation, and enhances editorial workflows across a wide range of use cases – from productivity boosts and proof-reading to content quality and consistency.

If you wish to test CKEditor AI, the access to it is enabled on [the free trial](https://portal.ckeditor.com/signup?callbackUrl=/checkout?plan%3Dfree).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo">

### Demo

* **AI Chat**  – Use the AI Chat in the side panel to create and edit content on the go with natural language. For example, ask in the chat to add emojis to headings in the content.
* **AI Chat History**  – Check history for past conversations in the document.
* **AI Quick Actions**  – Select content and use the balloon toolbar dropdown for Quick Actions and choose from predefined commands.
* **AI Review**  – Run the review with the improve clarity command.
* **AI Translate**  – Translate content to various languages with AI-powered translation suggestions.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--why-choose-ckeditor-ai">

### Why choose CKEditor AI?

CKEditor AI is an AI-powered writing assistant that integrates directly into our rich-text editor, CKEditor 5, providing instant text rewriting, summarization, correction, and contextual chat help based on internal style guides. The platform includes automated review tools and enterprise-ready functionality that plugs into existing systems without requiring custom infrastructure.

Teams can implement a full suite of AI writing tools in weeks rather than months, delivering streamlined, compliant content workflows that maintain brand consistency and integrate seamlessly with existing document management systems.

The core components of CKEditor AI are:

* CKEditor 5: A modern rich text editor with dozens of features that improve writing workflows, including collaboration.
* AI Service: A state-of-the-art backend AI engine that incorporates multiple models and delivers high-quality content. Available as a [Cloud (SaaS) or on-premises deployment](#ckeditor5/latest/features/ai/ckeditor-ai-deployment.html). The AI Service also provides a REST API.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ckeditor-ai-features">

### CKEditor AI features

There are four main features of CKEditor AI. Each feature is a standalone plugin that can be enabled or disabled independently, so you can tailor the AI experience to your needs. Refer to the [integration guide](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--enabling-individual-features) to learn how to configure them selectively. You can test them all using [the free trial](https://portal.ckeditor.com/signup?callbackUrl=/checkout?plan%3Dfree).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ai-chat">

#### AI Chat

The [CKEditor AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) is a conversational AI that can be used to aid content creation and editing. It introduces a dynamic chat interface designed to facilitate rich, multi-turn interactions between users and an AI Assistant. This capability moves beyond single-prompt content generation, enabling a more interactive and collaborative experience within writing workflows. It also provides context setting and model selection to better suit the needs of specific content and holds chat history for quick reference of previous work.

The Chat is also capable of using the web for more up-to-date information and reasoning to think more deeply about the answers and changes it is allowed to make.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ai-quick-actions">

#### AI Quick actions

[Quick actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html) streamline routine content transformations by offering one-click AI-powered suggestions directly within the editor. You can also ask questions about your selected text in the Chat to get instant AI insights and analysis. This feature enhances speed, relevance, and usability, particularly for repeatable or simple tasks, while preserving deeper chat-based functionality when needed.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ai-review">

#### AI Review

The [Review](#ckeditor5/latest/features/ai/ckeditor-ai-review.html) feature provides users with AI-powered quality assurance for their content by running checks for grammar, style, tone, and more. It also introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ai-translate">

#### AI Translate

The [AI Translate](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html) feature provides users with AI-powered translations. It introduces an intuitive interface for reviewing and managing AI-suggested translations directly within the document, ensuring content is translated with minimal manual effort.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--permissions">

### Permissions

Developers can control access to AI features, models, and capabilities based on user roles, subscription tiers, and organizational requirements. [Learn more about the permissions system](#cs/latest/guides/ckeditor-ai/permissions.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--privacy-and-data-handling">

### Privacy and data handling

You can find detailed information on how CKEditor AI manages your data in [Cloud Services documentation](#cs/latest/guides/ckeditor-ai/overview.html--data-handling-and-security).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--programmatic-usage">

### Programmatic usage

CKEditor AI features can also be controlled entirely from code – useful for building custom UI, automating workflows, or integrating AI capabilities into your application logic beyond the built-in editor toolbar.

The programmatic usage covers two approaches:

* **Front-end editor API** – Trigger AI Chat messages and Quick Actions directly from the editor instance.
* **REST API** – Call the AI service from your frontend to build AI-powered features around the editor.

See the [programmatic usage guide](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) for details, examples, and live demos.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--known-issues-and-caveats">

### Known issues and caveats

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--general-html-support">

#### General HTML Support

CKEditor AI may not work correctly when [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) for block elements is enabled. This issue will be addressed in future updates. In the meantime, we recommend avoiding configurations that may cause problems. Learn more about the [configuration of the General HTML Support feature](#ckeditor5/latest/features/html/general-html-support.html--configuration).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--issues-with-tables">

#### Issues with tables

We are aware of certain glitches that may occur when the AI modifies complex [tables](#ckeditor5/latest/features/tables/tables.html) or [layout tables](#ckeditor5/latest/features/tables/layout-tables.html). To prevent data loss, please ensure that the content around these structures remains intact when using CKEditor AI tools, while our team investigates the causes and potential solutions to this issue.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--editor-context-and-multiple-editor-handling">

#### Editor context and multiple editor handling

While it’s possible to use CKEditor AI with multiple editors in an [editor context](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html), only the first editor registered in the context will currently be able to interact with AI tools and benefit from the content suggestions made by the AI. As our team works on resolving this issue, we recommend using standalone editor instances with CKEditor AI.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--inline-image-processing-issues">

#### Inline image processing issues

[Inline images](#ckeditor5/latest/features/images/images-overview.html) may not be processed correctly by commands within the AI Review feature. A solution is currently under development.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--no-markdown-output-support">

#### No Markdown output support

CKEditor AI does not currently support output in [Markdown](#ckeditor5/latest/features/markdown.html) format. The AI response pipeline relies on HTML-based collaboration markers and suggestion highlights to power features like [Track Changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) and [Comments](#ckeditor5/latest/features/collaboration/comments/comments.html). These markers have no equivalent in Markdown, making HTML the only supported output format for now.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--limited-interactivity-in-chat-history">

#### Limited interactivity in Chat history

The interactivity of [historical AI Chat conversations](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--chat-history) can become limited over time.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--issues-with-gemini-3-pro-model">

#### Issues with Gemini 3 Pro model

The Gemini 3 Pro model may occasionally return empty responses. If this occurs, we recommend sending a follow-up message asking the Assistant to complete the previous request, or starting a new conversation.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--common-api">

### Common API

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--ui-components">

#### UI components

The AI features register the following UI components:

| [Component](#ckeditor5/latest/getting-started/setup/toolbar.html) name | Registered by                                                                                 |  | The 'toggleAi' button | [AIEditorIntegration](../../api/module%5Fai%5Faieditorintegration%5Faieditorintegration-AIEditorIntegration.html) |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |  | --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| The 'aiQuickActions' dropdown                                          | [AIQuickActions](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActions.html) |  |                       |                                                                                                                   |
| The 'ask-ai' button                                                    |                                                                                               |  |                       |                                                                                                                   |
| The 'explain' button                                                   |                                                                                               |  |                       |                                                                                                                   |
| The 'summarize' button                                                 |                                                                                               |  |                       |                                                                                                                   |
| The 'highlight-key-points' button                                      |                                                                                               |  |                       |                                                                                                                   |
| The 'improve-writing' button                                           |                                                                                               |  |                       |                                                                                                                   |
| The 'continue' button                                                  |                                                                                               |  |                       |                                                                                                                   |
| The 'fix-grammar' button                                               |                                                                                               |  |                       |                                                                                                                   |
| The 'make-shorter' button                                              |                                                                                               |  |                       |                                                                                                                   |
| The 'make-longer' button                                               |                                                                                               |  |                       |                                                                                                                   |
| The 'make-tone-casual' button                                          |                                                                                               |  |                       |                                                                                                                   |
| The 'make-tone-direct' button                                          |                                                                                               |  |                       |                                                                                                                   |
| The 'make-tone-friendly' button                                        |                                                                                               |  |                       |                                                                                                                   |
| The 'make-tone-confident' button                                       |                                                                                               |  |                       |                                                                                                                   |
| The 'make-tone-professional' button                                    |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-english' button                                      |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-chinese' button                                      |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-french' button                                       |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-german' button                                       |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-italian' button                                      |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-portuguese' button                                   |                                                                                               |  |                       |                                                                                                                   |
| The 'translate-to-russian' button                                      |                                                                                               |  |                       |                                                                                                                   |

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--editor-commands">

#### Editor commands

| [Component](#ckeditor5/latest/getting-started/setup/toolbar.html) name | Command class | Belongs to (top–level plugin) |  | The 'toggleAi' command | [ToggleAICommand](../../api/module%5Fai%5Faieditorintegration%5Faitogglebutton%5Ftoggleaicommand-ToggleAICommand.html) | [AIEditorIntegration](../../api/module%5Fai%5Faieditorintegration%5Faieditorintegration-AIEditorIntegration.html) |
| ---------------------------------------------------------------------- | ------------- | ----------------------------- |  | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |

<a id="ckeditor5/latest/features/ai/ckeditor-ai-overview.html--future-ideas-share-your-feedback">

### Future ideas - share your feedback!

Have an idea for future improvements? We’d love to hear from you! Share your thoughts and suggestions with us through our [contact form](https://ckeditor.com/contact/).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html"</a>

## Using CKEditor AI programmatically

CKEditor AI features are designed to work seamlessly through the built-in UI – but they can also be controlled entirely from code. This page covers two distinct approaches to using AI programmatically: the front-end editor API and the REST API.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--architecture-overview">

### Architecture overview

Out of the box, CKEditor 5 communicates with the CKEditor AI Service automatically – AI Chat, Quick Actions, Review, and Translate work without any extra setup. The diagram below shows how this fits into your application and what you can build around it.

Beyond the built-in features, you can extend AI capabilities in several ways:

* **Custom frontend logic:** call the AI service directly using the [REST API](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--rest-api) or the [editor’s API](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--front-end-editor-api) to build features outside the editor UI, such as generating titles, summaries, or metadata.
* **Custom backend logic:** automate AI workflows server-side via the [REST API](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--rest-api) for bulk processing, content pipelines, or scheduled tasks.
* **[MCP servers](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html):** connect external tools and data sources to the AI service via the Model Context Protocol (on-premises deployments only). [Contact us](https://ckeditor.com/contact/) to learn more.
* **Internal AI platform:** connect your AI platform with custom features to the CKEditor AI service backend (on-premises only, available on demand). [Contact us](https://ckeditor.com/contact/) to learn more.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--front-end-editor-api">

### Front-end editor API

CKEditor AI features can be triggered programmatically via the editor instance. This is useful for building custom UI, automating workflows, or integrating AI capabilities into your application logic beyond the built-in editor toolbar.

All examples below assume the editor is already set up with AI features enabled. See the [integration guide](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html) for setup instructions.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--chat">

#### Chat

The [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) feature can be controlled via the `AIChat` plugin. See the [chat documentation](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) for more details on the feature.

The demo below shows a generic sales offer for server infrastructure. Select a target company, then click the button to send a personalized rewrite request to AI Chat – all from code, without any user interaction in the chat UI. The prompt includes the company’s profile data so the AI tailors the offer accordingly.

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--send-a-message">

##### Send a message

Use the [sendMessage()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-sendMessage) method to programmatically send a message to AI Chat. You can dynamically construct the message based on your application state – for example, including external data like a company profile:

```
const aiChatController = editor.plugins.get( 'AIChatController' );

await aiChatController.sendMessage( {
    message: `Rewrite this offer for ${ companyName }.\n\nCompany profile:\n${ profileData }`
} );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--start-a-new-conversation">

##### Start a new conversation

Use the [startConversation()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-startConversation) method:

```
const aiChatController = editor.plugins.get( 'AIChatController' );

await aiChatController.startConversation();

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--add-editor-selection-to-chat-context">

##### Add editor selection to chat context

Attach the current editor selection as context for the next chat message using [addSelectionToChatContext()](../../api/module%5Fai%5Faichat%5Faichatcontroller-AIChatController.html#function-addSelectionToChatContext):

```
const aiChatController = editor.plugins.get( 'AIChatController' );

aiChatController.addSelectionToChatContext();

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--quick-actions">

#### Quick Actions

The [Quick Actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html) feature lets you trigger predefined AI actions programmatically via the `AIActions` plugin. See the [quick actions documentation](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html) for the full list of available actions and configuration options.

The demo below shows a payment reminder email with hardcoded customer data. The editor is configured with [merge fields](#ckeditor5/latest/features/merge-fields.html) for customer name, amount, due date, and other placeholders. Click the button to run a custom AI action that automatically replaces the hardcoded values with the appropriate merge field placeholders – built from the editor’s merge fields configuration.

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

Quick actions operate on the current editor selection. If the selection is collapsed (no text is selected), the action automatically expands to the nearest block element.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--execute-an-action-directly">

##### Execute an action directly

Use the [executeAction()](../../api/module%5Fai%5Faiactions%5Faiactions-AIActions.html#function-executeAction) method to run system actions or fully custom prompts:

```
const aiActions = editor.plugins.get( 'AIActions' );

// Run a system action.
await aiActions.executeAction(
    { actionName: 'improve-writing' },
    'Improve writing'
);

// Or run a custom prompt (model is required for custom actions).
await aiActions.executeAction(
    { userMessage: 'Rewrite the selected text as a haiku', model: 'agent-1' },
    'Make it a haiku'
);

```

The available system `actionName` values are defined by the [AIActionsNames](../../api/module%5Fai%5Faiactions%5Faiactions-AIActionsNames.html).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--rest-api">

### REST API

The same AI service that powers the editor features is also available as a REST API. You can call it from your frontend – using the editor’s authentication token – to build AI-powered features around the editor. This is especially useful for scenarios where you need AI capabilities **outside** the editor content area, such as auto-generating a title or meta description in separate form fields based on the editor content.

The demo below shows a form with a title and meta description field above the editor. Click the button to generate both fields from the editor content using the AI REST API.

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--what-you-can-do">

#### What you can do

The AI REST API (`https://ai.cke-cs.com`) exposes three categories of endpoints:

* **[Actions](#cs/latest/guides/ckeditor-ai/actions.html)** – Stateless, single-purpose content transforms. Use these for operations like fixing grammar, improving writing, translating short sections, adjusting length or tone, or running custom prompts against content.
* **[Conversations](#cs/latest/guides/ckeditor-ai/conversations.html)** – Multi-turn chat with conversation history, file uploads, and web search capabilities.
* **[Reviews](#cs/latest/guides/ckeditor-ai/reviews.html)** – Document analysis for grammar, clarity, readability, and tone, returning specific suggestions for improvement. Also supports full-document translation, ensuring all text is translated even in longer content.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--calling-the-rest-api-from-the-frontend">

#### Calling the REST API from the frontend

AI generation endpoints, such as Actions calls and Conversation message calls, return **Server-Sent Events (SSE)** streams. This means you cannot simply `await response.json()` for these responses – instead, you need to read the response stream and parse the individual events. Other REST API endpoints, such as the models endpoint, return regular JSON responses.

The following example shows how to call the AI Actions API from the browser and collect the streamed result:

```
// Get the editor content.
const html = editor.getData();

// Get the auth token from the editor's token provider.
const token = editor.plugins.get( 'CloudServices' ).token.value;

// Call the AI Actions API (system action: improve-writing).
const response = await fetch( 'https://ai.cke-cs.com/v1/actions/system/improve-writing/calls', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${ token }`
    },
    body: JSON.stringify( {
        content: [
            {
                type: 'text',
                content: html
            }
        ]
    } )
} );

// Read the SSE stream.
// Each SSE message has an "event:" line (e.g. "text-delta") and a "data:" line with JSON.
const reader = response.body.getReader();
const decoder = new TextDecoder();
let result = '';
let currentEvent = '';

while ( true ) {
    const { done, value } = await reader.read();

    if ( done ) {
        break;
    }

    const chunk = decoder.decode( value, { stream: true } );

    for ( const line of chunk.split( '\n' ) ) {
        if ( line.startsWith( 'event: ' ) ) {
            currentEvent = line.slice( 7 ).trim();
        } else if ( line.startsWith( 'data: ' ) && currentEvent === 'text-delta' ) {
            const data = JSON.parse( line.slice( 6 ) );

            result += data.textDelta;
        }
    }
}

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html--full-rest-api-documentation">

#### Full REST API documentation

For the complete API reference, including all available endpoints, request and response formats, streaming, and authentication details, see the [AI REST API documentation](https://ai.cke-cs.com/docs).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-review.html"</a>

## AI Review

The AI Review feature provides users with AI-powered quality assurance for their content by running checks for grammar, style, tone, and more. It also introduces an intuitive interface for reviewing and managing AI-suggested edits directly within the document, ensuring content meets professional standards with minimal manual effort.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--demo">

### Demo

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--integration">

### Integration

To start using the AI Review feature, first load the `AIReviewMode` plugin in your editor configuration. The AI Review button  will appear in the AI user interface. [Learn more about installing and enabling AI features](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html).

After picking one of the available commands in the AI Review tab, AI will analyze the document and propose a series of suggestions:

While in the AI Review, the editor remains read–only and allows you to browse suggestions. You can either click suggestions in the sidebar or select them in the editor content (underlined):

You can accept or dismiss review suggestions by clicking the corresponding buttons. You can also accept all suggestions by using the “Accept all” button in the top of the user interface and [preview changes similar to chat suggestions](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--previewing-changes). Changes that were accepted or dismissed become greyed out in the interface. You can also abandon the review by hitting the “Exit review” button.

Once you are done reviewing your document and all changes are accepted or rejected, click “Finish review” (the button state changes automatically) to return to the normal operation of the editor, where typing is possible.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--review-commands">

### Review commands

The feature comes with several review commands:

| Command name              | Command description                                                | Additional information                                                                                                                                                                                                                                                                                   | Configuration id |
| ------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Custom command**        | Enter a custom command for a specific review.                      | You can pick one of the [available AI models](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--supported-ai-models) to execute a custom command. The default model is selected based on the [model configuration](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--configuration). | custom           |
| **Proofread**             | Check the text for errors in grammar, spelling and punctuation.    |                                                                                                                                                                                                                                                                                                          | correctness      |
| **Improve clarity**       | Improve the logical structure and precision for a clearer message. |                                                                                                                                                                                                                                                                                                          | clarity          |
| **Improve readability**   | Adjust sentence structure and word choice for an easier read.      |                                                                                                                                                                                                                                                                                                          | readability      |
| **Adjust length**         | Shorten or lengthen the text as needed.                            | _Longer_ and _Shorter_ options available                                                                                                                                                                                                                                                                 | length           |
| **Adjust tone and style** | Modify the text to a desired tone and style.                       | Several tone and style options are available: _Casual, Direct, Friendly, Confident, Professional_                                                                                                                                                                                                        | tone             |

The list of review commands visible in the AI Review UI can be adjusted by reordering them or removing selected ones. Please refer to the [Available review commands section](#ckeditor5/latest/features/ai/ckeditor-ai-review.html--available-review-commands) below.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--available-review-commands">

#### Available review commands

The list of available review commands visible in the AI Review UI can be adjusted via `config.ai.review.availableCommands`. This configuration option accepts a list of command IDs. The order of IDs on the list defines the order of commands in the UI. You can limit the list of commands to only desired ones and reorder them at the same time:

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIReviewMode, AIEditorIntegration, /* ... */ ],

        ai: {
            review: {
                availableCommands: [
                    'length',
                    'tone',
                    'readability',
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Please refer to the [Review commands section](#ckeditor5/latest/features/ai/ckeditor-ai-review.html--review-commands) above to see all available commands.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--available-models-for-custom-command">

#### Available models for custom command

The AI Review feature uses the unified [model configuration](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--configuration) from `config.ai.models`, which is shared across all AI features ([Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) and Review). This ensures consistent model selection behavior across your AI features.

When using the Custom command, the default model is automatically selected based on the `defaultModelId` configuration. You can also manually select a different model from the available models list, which is filtered by the `displayedModels` configuration.

The model selector UI visibility is controlled by the [config.ai.models.showModelSelector](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html--configuration) setting.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--adding-extra-commands">

#### Adding extra commands

The AI Review feature supports adding custom commands tailored to your specific needs. Each custom command requires a custom prompt definition. You can optionally specify a model ID to use a particular model instead of the default one.

The command definition needs to be provided via `config.ai.review.extraCommands` configuration option. This option registers the command in the AI Review feature.

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIReviewMode, AIEditorIntegration, /* ... */ ],

        ai: {
            review: {
                extraCommands: [
                    {
                        id: 'improve-captions',
                        label: 'Improve Captions',
                        description: 'Improve image captions in the document.',
                        prompt: 'Suggest improvements for the image captions in the document.',
                    },
                    {
                        id: 'expand-abbreviations',
                        label: 'Expand Abbreviations',
                        description: 'Expand abbreviations in the document.',
                        prompt: 'Suggest expansions for abbreviations in the document.',
                        model: 'gpt-5-2'
                    }
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If [config.ai.review.availableCommands configuration option](#ckeditor5/latest/features/ai/ckeditor-ai-review.html--available-review-commands) is not set, the extra commands will be added to the end of the list of available commands and visible in the UI by default. However, once `config.ai.review.availableCommands` is defined, it overrides the default list. In this case, you must explicitly include all commands that should be available in the UI (both default and extra ones), as only the commands listed in this configuration will be exposed:

```
ClassicEditor
    .create( {
        /* ... */

        plugins: [ AIReviewMode, AIEditorIntegration, /* ... */ ],

        ai: {
            review: {
                availableCommands: [
                    'improve-captions',
                    'expand-abbreviations',

                    'custom',
                    'correctness',
                    'clarity',
                    'readability',
                    'length',
                    'tone',
                ],
                extraCommands: [ /* ... */ ],
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--common-api">

### Common API

<a id="ckeditor5/latest/features/ai/ckeditor-ai-review.html--rest-api">

#### REST API

Document reviews are also available via the [Reviews REST API](#cs/latest/guides/ckeditor-ai/reviews.html). Use this to analyze documents for grammar, clarity, readability, and tone outside the editor, returning specific suggestions for improvement. See the [programmatic documentation](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) for examples and the [full API reference](https://ai.cke-cs.com).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html">source file: "ckeditor5/latest/features/ai/ckeditor-ai-translate.html"</a>

## AI Translate

The AI Translate feature provides users with AI-powered translations. It introduces an intuitive interface for reviewing and managing AI-suggested translations directly within the document, ensuring content meets professional standards with minimal manual effort.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--demo">

### Demo

This demo presents a limited set of AI features. Visit the [CKEditor AI overview](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html--demo) to see more in action.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--integration">

### Integration

To start using the Translate feature, first load the `AITranslate` plugin in your editor configuration. The translate button  will appear in the AI user interface. [Learn more about installing and enabling AI features](#ckeditor5/latest/features/ai/ckeditor-ai-integration.html).

After choosing one of the available languages in the Translate tab, AI will analyze the document and propose a translation. While in the Translate Mode, the editor remains read-only and allows you to browse translation suggestions. Translation suggestions can be seen in the editor content, visualizing how a fully translated document will look:

While the Translate tab shows the original content for better context:

You can either click suggestions in the sidebar or select them in the editor content (underlined) to see which translation applies to which part of the original content:

You can accept translations by using the “Accept translation” button at the top of the user interface. You can also abandon the review by hitting the “Cancel” button.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--languages-list">

### Languages list

The default list of languages includes several languages out-of-the-box: _English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, and Italian_. The list can be [fully customized](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html--customizing-list-of-languages).

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--customizing-list-of-languages">

#### Customizing list of languages

The [config.ai.translate.languages](../../api/module%5Fai%5Faitranslate%5Faitranslate-AITranslateConfig.html#member-languages) property allows you to provide a custom list of languages for the “Translate” feature. For instance, the following configuration will replace the default list with “German” and “French”:

```
ClassicEditor
    .create( {
        ai: {
            translate: {
                languages: [
                    {
                        id: 'german',
                        label: 'German'
                    },
                    {
                        id: 'french',
                        label: 'French'
                    }
                ]
            }
        }
    } )
    .then( ... )
    .catch( ... );

```

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--supported-languages">

#### Supported languages

The AI Translate feature supports multiple languages with varying quality levels. The production-ready languages (_English, Spanish, French, German, Chinese (Simplified), Japanese, Russian, Portuguese, Korean, Italian_) offer the most reliable results for any-to-any translation pairs. Extended support is available for 40+ additional languages based on LLM provider capabilities, though quality may vary depending on the language pair and content complexity.

Translation quality is generally highest for _English-to-X_ or _X-to-English_ pairs, while any-to-any translation between non-English languages outside the production tier may produce less reliable results, particularly with specialized vocabulary.

[Contact us](https://ckeditor.com/contact/) if you need more specific translation capabilities.

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--common-api">

### Common API

<a id="ckeditor5/latest/features/ai/ckeditor-ai-translate.html--rest-api">

#### REST API

Translation is available via the REST API through two endpoints, depending on the scope of the content:

* **[Actions](#cs/latest/guides/ckeditor-ai/actions.html)** – Best for translating short text sections. The `translate` action performs a single-pass translation of the provided content.
* **[Reviews](#cs/latest/guides/ckeditor-ai/reviews.html)** – Best for full documents. The review-based translation ensures all text is translated, including parts that a single-pass action might miss in longer content.

See the [programmatic documentation](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) for examples and the [full API reference](https://ai.cke-cs.com).

<a id="ckeditor5/latest/features/autoformat.html">source file: "ckeditor5/latest/features/autoformat.html"</a>

## Autoformatting

The autoformat feature lets you quickly format your content with Markdown-like shortcodes. This way you do not need to use toolbar buttons or dropdowns for the most common formatting features.

<a id="ckeditor5/latest/features/autoformat.html--demo">

### Demo

Test the autoformatting feature in the editor below. Try using Markdown shortcodes while typing. For example:

1. Start a new line.
2. Press # and then Space.

The line will automatically turn into a heading.

If needed, you can revert the automatic change by pressing Backspace.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/autoformat.html--block-formatting">

### Block formatting

The following block formatting options are available:

* [Bulleted list](#ckeditor5/latest/features/lists/lists.html) – Start a line with `*` or `-` followed by a space.
* [Numbered list](#ckeditor5/latest/features/lists/lists.html) – Start a line with `1.` or `1)` followed by a space.
* [To-do list](#ckeditor5/latest/features/lists/todo-lists.html) – Start a line with `[ ]` or `[x]` followed by a space to insert an unchecked or checked list item, respectively.
* [Headings](#ckeditor5/latest/features/headings.html) – Start a line with `#` or `##` or `###` followed by a space to create a heading 1, heading 2, or heading 3 (up to heading 6 if [options](../api/module%5Fheading%5Fheadingconfig-HeadingConfig.html#member-options) defines more headings).
* [Block quote](#ckeditor5/latest/features/block-quote.html) – Start a line with `>` followed by a space.
* [Code block](#ckeditor5/latest/features/code-blocks.html) – Start a line with `` `backticks` ``.
* [Horizontal line](#ckeditor5/latest/features/horizontal-line.html) – Start a line with `---`.

<a id="ckeditor5/latest/features/autoformat.html--inline-formatting">

### Inline formatting

The following [basic styles](#ckeditor5/latest/features/basic-styles.html) inline formatting options are available:

* Bold – Type `**text**` or `__text__`,
* Italic – Type `*text*` or `_text_`,
* Code – Type `` `text` ``,
* Strikethrough – Type `~~text~~`.

<a id="ckeditor5/latest/features/autoformat.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/autoformat.html--creating-custom-autoformatters">

### Creating custom autoformatters

The [Autoformat](../api/module%5Fautoformat%5Fautoformat-Autoformat.html) feature bases on [blockAutoformatEditing](../api/module%5Fautoformat%5Fblockautoformatediting.html#function-blockAutoformatEditing) and [inlineAutoformatEditing](../api/module%5Fautoformat%5Finlineautoformatediting.html#function-inlineAutoformatEditing) tools to create the autoformatters mentioned above.

You can use these tools to create your own autoformatters. Check the [Autoformat feature’s code](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-autoformat/src/autoformat.ts) as an example.

<a id="ckeditor5/latest/features/autoformat.html--known-issues">

### Known issues

While the autoformatting feature is stable and ready to use, some issues were reported for it. Feel free to upvote 👍 them on GitHub if they are important for you:

* Pasting Markdown-formatted content does not automatically convert the pasted syntax markers into properly formatted content. GitHub issues: [#2321](https://github.com/ckeditor/ckeditor5/issues/2321), [#2322](https://github.com/ckeditor/ckeditor5/issues/2322).
* Setting a specific code block language is not supported yet (it defaults to plain text on insertion). GitHub issue: [#8598](https://github.com/ckeditor/ckeditor5/issues/8598).

<a id="ckeditor5/latest/features/autoformat.html--related-features">

### Related features

In addition to enabling automatic text formatting, you may want to check the following productivity features:

* [Automatic text transformation](#ckeditor5/latest/features/text-transformation.html) – Enables automatic turning of snippets such as `(tm)` into `™` and `"foo"` into `“foo”`.
* [Autolink](#ckeditor5/latest/features/link.html--autolink-feature) – Turns the links and email addresses typed or pasted into the editor into active URLs.
* [Mentions](#ckeditor5/latest/features/mentions.html) – Brings support for smart autocompletion.
* [Slash commands](#ckeditor5/latest/features/slash-commands.html) – Allows to execute a predefined command by writing its name or alias directly in the editor.
* [Markdown output](#ckeditor5/latest/features/markdown.html) – Lets the user output the content as Markdown instead of HTML and [use CKEditor 5 as a WYSIWYG Markdown editor](https://ckeditor.com/blog/CKEditor-5-the-best-open-source-Markdown-editor/).
* [Source editing](#ckeditor5/latest/features/source-editing/source-editing.html--markdown-source-view) – Allows for Markdown source edition if configured accordingly.

Coupled with the [Markdown output](#ckeditor5/latest/features/markdown.html) feature, the autoformatting feature allows for the full-fledged Markdown WYSIWYG editing experience, as described in the [“CKEditor 5: the best open source Markdown editor”](https://ckeditor.com/blog/CKEditor-5-the-best-open-source-Markdown-editor/) blog post. Visit the [free online Markdown editor](https://onlinemarkdowneditor.dev/) to see this solution implemented.

<a id="ckeditor5/latest/features/autoformat.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-autoformat>.

<a id="ckeditor5/latest/features/autosave.html">source file: "ckeditor5/latest/features/autosave.html"</a>

## Autosave

The autosave feature allows you to automatically save the data (for example, send it to the server) when needed. This can happen, for example, when the user changes the content.

<a id="ckeditor5/latest/features/autosave.html--demo">

### Demo

Type some text in the demo below to try out the autosave feature. Try adding rich content such as images or tables, and observe the feature’s behavior. Demo elements and mechanisms are explained below the editor.

How to understand this demo:

* The status indicator shows if the editor has some unsaved content or pending actions.  
  * If you drop a big image into this editor, you will see that it is busy during the entire period when the image is being uploaded.
  * The editor is also busy when saving the content is in progress (the `save()`'s promise was not resolved).
* The autosave feature has a throttling mechanism that groups frequent changes (like typing) into batches.
* The autosave itself does not check whether the data has actually changed. It bases on changes in the [model](#ckeditor5/latest/framework/architecture/editing-engine.html--model) that sometimes may not be “visible” in the data. You can add such a check yourself if you would like to avoid sending the same data to the server twice.
* You will be asked whether you want to leave the page if an image is being uploaded or the data has not been saved successfully yet. You can test that by dropping a big image into the editor or changing the “HTTP server lag” to a high value (for example, 9000ms) and typing something. These actions will make the editor busy for a longer time – try leaving the page then.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/autosave.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list.

Assuming that you have implemented some form of the `saveData()` function that sends the data to your server and returns a promise which is resolved once the data is successfully saved, configuring the [Autosave](../api/module%5Fautosave%5Fautosave-Autosave.html) feature is simple:

The autosave feature listens to the [editor.model.document#change:data](../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event, throttles it, and executes the [config.autosave.save()](../api/module%5Fautosave%5Fautosave-AutosaveConfig.html#member-save) function.

It also listens to the native [window#beforeunload](https://developer.mozilla.org/en-US/docs/Web/Events/beforeunload) event and blocks it in the following cases:

* The data has not been saved yet (the `save()` function did not resolve its promise or it has not been called yet due to throttling).
* Or any of the editor features registered a [“pending action”](../api/module%5Fcore%5Fpendingactions-PendingActions.html) (for example, that an image is being uploaded).

This automatically secures you from the user leaving the page before the content is saved or some ongoing actions like image upload did not finish.

<a id="ckeditor5/latest/features/autosave.html--configuration">

### Configuration

You can configure the minimum period between two save actions using the [config.waitingTime](../api/module%5Fautosave%5Fautosave-AutosaveConfig.html#member-waitingTime) property. This helps to avoid overloading the backend.

One second is the default waiting time before the next save action if nothing has changed after the editor data was last saved.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        autosave: {
            waitingTime: 5000, // in ms
            save( editor ) {}
        },
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/autosave.html--demo-code">

#### Demo code

The demo example at the beginning of this guide shows a simple integration of the editor with a fake HTTP server (which needs 1000ms to save the content). Here is the demo code:

```
ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        // ... Other configuration options ...
        autosave: {
            save( editor ) {
                return saveData( editor.getData() );
            }
        }
    } )
    .then( editor => {
        window.editor = editor;

        displayStatus( editor );
    } )
    .catch( err => {
        console.error( err.stack );
    } );

// Save the data to a fake HTTP server (emulated here with a setTimeout()).
function saveData( data ) {
    return new Promise( resolve => {
        setTimeout( () => {
            console.log( 'Saved', data );

            resolve();
        }, HTTP_SERVER_LAG );
    } );
}

// Update the "Status: Saving..." information.
function displayStatus( editor ) {
    const pendingActions = editor.plugins.get( 'PendingActions' );
    const statusIndicator = document.querySelector( '#editor-status' );

    pendingActions.on( 'change:hasAny', ( evt, propertyName, newValue ) => {
        if ( newValue ) {
            statusIndicator.classList.add( 'busy' );
        } else {
            statusIndicator.classList.remove( 'busy' );
        }
    } );
}

```

<a id="ckeditor5/latest/features/autosave.html--related-features">

### Related features

You can read more about [getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) in the Getting started section.

<a id="ckeditor5/latest/features/autosave.html--common-api">

### Common API

The [Autosave](../api/module%5Fautosave%5Fautosave-Autosave.html) plugin registers the [AutosaveAdapter](../api/module%5Fautosave%5Fautosave-AutosaveAdapter.html) used to save the data.

You can use [AutosaveConfig](../api/module%5Fautosave%5Fautosave-AutosaveConfig.html) to control the behavior of the adapter.

<a id="ckeditor5/latest/features/autosave.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-autosave>.

<a id="ckeditor5/latest/features/basic-styles.html">source file: "ckeditor5/latest/features/basic-styles.html"</a>

## Basic text styles

The basic styles feature lets you apply the most essential formatting such as bold, italic, underline, strikethrough, subscript, superscript, and code. Coupled with more [formatting features](#ckeditor5/latest/features/basic-styles.html--related-features), these serve as a base for any WYSIWYG editor toolset.

<a id="ckeditor5/latest/features/basic-styles.html--demo">

### Demo

You may apply basic formatting options with toolbar buttons. You can also make use of the [autoformatting feature](#ckeditor5/latest/features/autoformat.html) that changes Markdown code to formatted text as you type. Use one of these to format text:

* Bold – Use the bold toolbar button  or type `**text**` or `__text__`.
* Italic – Use the italic toolbar button  or type `*text*` or `_text_`.
* Code – Use the code toolbar button  or type `` `text` ``.
* Strikethrough – Use the strikethrough toolbar button  or type `~~text~~`.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/basic-styles.html--available-text-styles">

### Available text styles

| Style feature                                                                    | [Command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) name | [Toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) component name | Output element         |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ---------------------- |
| [Bold](../api/module%5Fbasic-styles%5Fbold-Bold.html)                            | 'bold'                                                                                           | 'bold'                                                                         | <strong>bold</strong>  |
| [Italic](../api/module%5Fbasic-styles%5Fitalic-Italic.html)                      | 'italic'                                                                                         | 'italic'                                                                       | <i>italic</i>          |
| [Underline](../api/module%5Fbasic-styles%5Funderline-Underline.html)             | 'underline'                                                                                      | 'underline'                                                                    | <u>underline</u>       |
| [Strikethrough](../api/module%5Fbasic-styles%5Fstrikethrough-Strikethrough.html) | 'strikethrough'                                                                                  | 'strikethrough'                                                                | <s>strikethrough</s>   |
| [Code](../api/module%5Fbasic-styles%5Fcode-Code.html)                            | 'code'                                                                                           | 'code'                                                                         | <code>code</code>      |
| [Subscript](../api/module%5Fbasic-styles%5Fsubscript-Subscript.html)             | 'subscript'                                                                                      | 'subscript'                                                                    | <sub>subscript</sub>   |
| [Superscript](../api/module%5Fbasic-styles%5Fsuperscript-Superscript.html)       | 'superscript'                                                                                    | 'superscript'                                                                  | <sup>superscript</sup> |

<a id="ckeditor5/latest/features/basic-styles.html--supported-input">

#### Supported input

By default, each feature can upcast more than one type of content. Here is the full list of elements supported by each feature, either when pasting from the clipboard, loading data on start, or using the [data API](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData).

| Style feature                                                                    | Supported input elements                                                                        |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Bold](../api/module%5Fbasic-styles%5Fbold-Bold.html)                            | <strong>, <b>, <\* style="font-weight: bold"> (or numeric values that are greater or equal 600) |
| [Italic](../api/module%5Fbasic-styles%5Fitalic-Italic.html)                      | <i>, <em>, <\* style="font-style: italic">                                                      |
| [Underline](../api/module%5Fbasic-styles%5Funderline-Underline.html)             | <u>, <\* style="text-decoration: underline">                                                    |
| [Strikethrough](../api/module%5Fbasic-styles%5Fstrikethrough-Strikethrough.html) | <s>, <del>, <strike>, <\* style="text-decoration: line-through">                                |
| [Code](../api/module%5Fbasic-styles%5Fcode-Code.html)                            | <code>, <\* style="word-wrap: break-word">                                                      |
| [Subscript](../api/module%5Fbasic-styles%5Fsubscript-Subscript.html)             | <sub>, <\* style="vertical-align: sub">                                                         |
| [Superscript](../api/module%5Fbasic-styles%5Fsuperscript-Superscript.html)       | <sup>, <\* style="vertical-align: super">                                                       |

<a id="ckeditor5/latest/features/basic-styles.html--typing-around-inline-code">

### Typing around inline code

CKEditor 5 allows for typing both at the inner and outer boundaries of code to make editing easier for the users.

**To type inside a code element**, move the caret to its (start or end) boundary. As long as the code remains highlighted (by default: less transparent gray), typing and applying formatting will be done within its boundaries:

**To type before or after a code element**, move the caret to its boundary, then press the Arrow key (→ or ←) once. The code is no longer highlighted and whatever text you type or formatting you apply will not be enclosed by the code element:

<a id="ckeditor5/latest/features/basic-styles.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the plugins which you need to your plugin list. Then, simply configure the toolbar items to make the features available in the user interface.

<a id="ckeditor5/latest/features/basic-styles.html--related-features">

### Related features

Check out also these CKEditor 5 features to gain better control over your content style and format:

* [Font styles](#ckeditor5/latest/features/font.html) – Easily and efficiently control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Styles](#ckeditor5/latest/features/style.html) – Apply pre-configured styles to existing elements in the editor content.
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Because it does matter whether the content is left, right, centered, or justified.
* [Case change](#ckeditor5/latest/features/case-change.html) – Turn a text fragment or block into uppercase, lowercase, or title case.
* [Code blocks](#ckeditor5/latest/features/code-blocks.html) – Insert longer, multiline code listings, expanding the inline code style greatly.
* [Highlight](#ckeditor5/latest/features/highlight.html) – Mark important words and passages, aiding a review or drawing attention to specific parts of the content.
* [Format painter](#ckeditor5/latest/features/format-painter.html) – Easily copy text formatting and apply it in a different place in the edited document.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the text on the go with Markdown code.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/basic-styles.html--common-api">

### Common API

Each style feature registers a [command](#ckeditor5/latest/features/basic-styles.html--available-text-styles) which can be executed from code. For example, the following snippet will apply the bold style to the current selection in the editor:

```
editor.execute( 'bold' );

```

<a id="ckeditor5/latest/features/basic-styles.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles>.

<a id="ckeditor5/latest/features/block-quote.html">source file: "ckeditor5/latest/features/block-quote.html"</a>

## Block quote

The block quote feature lets you easily include block quotations or pull quotes in your content. It is also an attractive way to draw the readers’ attention to selected parts of the text.

<a id="ckeditor5/latest/features/block-quote.html--demo">

### Demo

Use the block quote toolbar button  in the editor below to see the feature in action. You can also type `>` followed by a space before the quotation to format it on the go thanks to the [autoformatting](#ckeditor5/latest/features/autoformat.html) feature.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/block-quote.html--nested-block-quotes">

### Nested block quotes

Starting from version 27.1.0, CKEditor 5 will properly display a block quote nested in another block quote. This sort of structure is indispensable in email editors or discussion forums. The ability to cite previous messages and preserve a correct quotation structure is often crucial to maintain the flow of communication. Nested block quotes may also prove useful for scientific or academic papers, but articles citing sources and referring to previous writing would often use it, too.

Support for nested block quotes is provided as backward compatibility for loading pre-existing content, for example created in CKEditor 4\. Additionally, pasting content with nested block quotes is supported. You can also nest a block quote in another block quote using the [drag and drop](#ckeditor5/latest/features/drag-drop.html) mechanism – just select an existing block quote and drag it into another.

<a id="ckeditor5/latest/features/block-quote.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/block-quote.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/block-quote.html--disallow-nesting-block-quotes">

#### Disallow nesting block quotes

By default, the editor supports inserting a block quote into another block quote.

To disallow nesting block quotes, you need to register an additional schema rule. It needs to be added before the data is loaded into the editor, hence it is best to implement it as a plugin:

```
function DisallowNestingBlockQuotes( editor ) {
    editor.model.schema.addChildCheck( ( context, childDefinition ) => {
        if ( context.endsWith( 'blockQuote' ) && childDefinition.name == 'blockQuote' ) {
            return false;
        }
    } );
}

// Pass it via config.extraPlugins or config.plugins:

ClassicEditor
    .create( {
        extraPlugins: [ DisallowNestingBlockQuotes ],

        // The rest of the configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/block-quote.html--related-features">

### Related features

Here are some other CKEditor 5 features that you can use similarly to the block quote plugin to structure your text better:

* [Block indentation](#ckeditor5/latest/features/indent.html) – Set indentation for text blocks such as paragraphs or lists.
* [Code block](#ckeditor5/latest/features/code-blocks.html) – Insert longer, multiline code listings.
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Align your content left, right, center it, or justify.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Add formatting elements (such as block quotes) as you type with Markdown code.

<a id="ckeditor5/latest/features/block-quote.html--common-api">

### Common API

The [BlockQuote](../api/module%5Fblock-quote%5Fblockquote-BlockQuote.html) plugin registers:

* the `'blockQuote'` UI button component implemented by the [block quote UI feature](../api/module%5Fblock-quote%5Fblockquoteui-BlockQuoteUI.html),
* the `'blockQuote'` command implemented by the [block quote editing feature](../api/module%5Fblock-quote%5Fblockquoteediting-BlockQuoteEditing.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Applies block quote to the selected content.
editor.execute( 'blockQuote' );

```

<a id="ckeditor5/latest/features/block-quote.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-block-quote>.

<a id="ckeditor5/latest/features/bookmarks.html">source file: "ckeditor5/latest/features/bookmarks.html"</a>

## Bookmarks

The bookmarks feature allows for adding and managing the bookmarks anchors attached to the content of the editor. These provide fast access to important content sections, speed up the editing navigation and contribute to a more efficient content creation.

<a id="ckeditor5/latest/features/bookmarks.html--demo">

### Demo

Use the bookmark toolbar button  in the editor below to see the feature in action. Or use the “Insert” command from the menu bar to add a bookmark. Add a unique name to identify the bookmark (for example, `Rights`). You can change the bookmark’s name or remove it by clicking the bookmark icon inside the content.

To use the bookmark as an anchor in the content, add a link  and put the bookmark name as target. In the example below it could be `#Rights`. The link insertion panel will display all bookmarks available in the edited content (see the [Integration with the link feature](#ckeditor5/latest/features/bookmarks.html--integration-with-the-link-feature) section below).

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/bookmarks.html--handling-the-anchor-markup">

### Handling the anchor markup

Do not worry about setting a bookmark inside an empty paragraph. The block with the `a` tag will not be rendered in the final content (for example for printing).

The feature converts anchors into bookmarks during the [initialization of the editor](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--initializing-the-editor-with-data) or while [replacing the editor data with setData()](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--replacing-the-editor-data-with-setdata). The notation based on the `id` attribute in an `a` HTML element without a `href` attribute is converted. Similar notations meet the conditions, too:

* an `a` HTML element with a `name` attribute,
* an `a` HTML element with the same `name` and `id` attributes,
* an `a` HTML element with different `name` and `id` attributes.

By default, all bookmarks created in the editor only have the `id="..."` attribute in the [editor data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--getting-the-editor-data-with-getdata).

<a id="ckeditor5/latest/features/bookmarks.html--integration-with-the-link-feature">

### Integration with the link feature

Bookmarks integrate with [links](#ckeditor5/latest/features/link.html), providing a smooth linking experience. If you have any bookmarks in your content, you can access the “Bookmarks” panel available during link creation. It will display all bookmarks available in the edited content. Choose one of the anchors from the list and use it as a link target.

<a id="ckeditor5/latest/features/bookmarks.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/bookmarks.html--configuration">

### Configuration

By default, the conversion of wrapped anchors is turned on. It allows to convert non-empty anchor elements into bookmarks. For example:

```
<a id="foo">Foo bar baz</a>

```

will be converted into a bookmark and the output will look like on the example below:

```
<a id="foo"></a>Foo bar baz

```

You can disable the automatic conversion by setting the [config.bookmark.enableNonEmptyAnchorConversion](../api/module%5Fbookmark%5Fbookmarkconfig-BookmarkConfig.html#member-enableNonEmptyAnchorConversion) to `false` in the editor configuration.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        bookmark: {
            enableNonEmptyAnchorConversion: false
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/bookmarks.html--bookmark-toolbar-configuration">

### Bookmark toolbar configuration

The bookmark UI contains a contextual toolbar that appears when a bookmark is selected. You can configure what items appear in this toolbar using the [config.bookmark.toolbar](../api/module%5Fbookmark%5Fbookmarkconfig-BookmarkConfig.html#member-toolbar) option.

The following toolbar items are available:

* `'bookmarkPreview'` – Shows the name of the bookmark.
* `'editBookmark'` – Opens a form to edit the bookmark name.
* `'removeBookmark'` – Removes the bookmark.

By default, the bookmark toolbar is configured as follows:

```
ClassicEditor
    .create( {
        bookmark: {
            toolbar: [ 'bookmarkPreview', '|', 'editBookmark', 'removeBookmark' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/bookmarks.html--custom-toolbar-items">

#### Custom toolbar items

You can extend the bookmark toolbar with custom items by registering them in the [component factory](../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html) and adding them to the toolbar configuration.

Here is an example of registering a custom component:

```
class MyCustomPlugin extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'myCustomBookmarkInfo', locale => {
            const button = new ButtonView( locale );
            const bookmarkCommand = editor.commands.get( 'insertBookmark' );

            button.bind( 'isEnabled' ).to( bookmarkCommand, 'value', href => !!href );
            button.bind( 'label' ).to( bookmarkCommand, 'value' );

            button.on( 'execute', () => {
                // Add your custom component logic here
            } );

            return button;
        } );
    }
}

```

Once registered, the component can be used in the toolbar configuration:

```
ClassicEditor
    .create( {
        plugins: [ MyCustomPlugin, /* ... */ ],
        bookmark: {
            toolbar: [ 'myCustomBookmarkInfo', '|', 'editBookmark', 'removeBookmark' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/bookmarks.html--bookmarks-on-blocks">

### Bookmarks on blocks

At this time, if a bookmark is attached to a block, it appears before it. However, we plan to expand this solution in the future. We invite you to help us [gather feedback for linking directly to blocks and auto generating IDs](https://github.com/ckeditor/ckeditor5/issues/17264).

<a id="ckeditor5/latest/features/bookmarks.html--related-features">

### Related features

Here are some other CKEditor 5 features that you can use similarly to the bookmark plugin to cross-link and structure your text better:

* The [link feature](#ckeditor5/latest/features/link.html) allows adding local and global URLs to the content.
* The [document outline](#ckeditor5/latest/features/document-outline.html) displays the list of sections (headings) of the document next to the editor.
* The [table of contents](#ckeditor5/latest/features/document-outline.html) lets you insert a widget with a list of headings (section titles) that reflects the structure of the document.

<a id="ckeditor5/latest/features/bookmarks.html--common-api">

### Common API

The [Bookmark](../api/module%5Fbookmark%5Fbookmark-Bookmark.html) plugin registers the `'bookmark'` UI button component implemented by the [bookmark UI feature](../api/module%5Fbookmark%5Fbookmarkui-BookmarkUI.html), and the following commands:

* the `'insertBookmark'` command implemented by the [editing feature](../api/module%5Fbookmark%5Finsertbookmarkcommand-InsertBookmarkCommand.html).
* the `'updateBookmark'` command implemented by the [editing feature](../api/module%5Fbookmark%5Fupdatebookmarkcommand-UpdateBookmarkCommand.html).

<a id="ckeditor5/latest/features/bookmarks.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-bookmark>.

<a id="ckeditor5/latest/features/case-change.html">source file: "ckeditor5/latest/features/case-change.html"</a>

## Case change

The case change feature lets you quickly change the letter case of the selected content. You can use it to format part of the text like a title or change it to all-caps and back.

<a id="ckeditor5/latest/features/case-change.html--demo">

### Demo

The demo below lets you test the case change. Place the cursor inside a block such as a paragraph, heading, or list item to affect the entire block. You can also select a text fragment you want to change. Then, apply the case formatting with the  toolbar dropdown.

You can also use the Shift+F3 keyboard shortcut to cycle through case formats: UPPERCASE > lowercase > Title Case. Undo changes with Ctrl/Cmd+Z.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/case-change.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/case-change.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/case-change.html--configuring-the-title-case-mode">

### Configuring the title case mode

Approaches to the title case change vary. This is why we did not add a default ruleset. You can use the [config.caseChange.titleCase](../api/module%5Fcase-change%5Fcasechange-CaseChangeTitleCaseConfig.html) configuration to apply your rules. The configuration allows for adding exclusions – words that the feature should not capitalize, as shown in the example below. It also provides an entry point for writing custom sentence end detection mechanisms to handle exclusions in special positions in the sentence.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        caseChange: {
            titleCase: {
                excludeWords: [ 'a', 'an', 'and', 'as', 'at', 'but', 'by', 'en', 'for', 'if', 'in',
                    'nor', 'of', 'on', 'or', 'per', 'the', 'to', 'vs', 'vs.', 'via' ]
            }
        },
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/case-change.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you format your content:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_ and others.
* [Font styles](#ckeditor5/latest/features/font.html) – Control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), and [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the text on the go using Markdown.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/case-change.html--common-api">

### Common API

The [CaseChange](../api/module%5Fcase-change%5Fcasechange-CaseChange.html) plugin registers:

* The `'caseChange'` UI dropdown component.
* The `'changeCaseUpper'`, `'changeCaseLower'`, and `'changeCaseTitle'` commands implemented by [CaseChangeCommand](../api/module%5Fcase-change%5Fcasechangecommand-CaseChangeCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Change the case of selected content to uppercase.
editor.execute( 'changeCaseUpper' );

// Change the case of selected content to lowercase.
editor.execute( 'changeCaseLower' );

// Change the case of selected content to title case.
editor.execute( 'changeCaseTitle' );

```

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html">source file: "ckeditor5/latest/features/cloud-services/cloud-services-overview.html"</a>

## Cloud Services Overview

The CKEditor Cloud Services is a cloud platform that provides editing and real-time collaboration services. These services for managing comments, storing document revisions, handling the users, synchronizing the data, utilizing, configuring and managing features, importing and exporting documents and managing assets.

The platform primarily focuses on providing a backend for the CKEditor 5 features (via dedicated plugins), although some features can also be used directly through [RESTful APIs and hooks](#ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html).

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--real-time-collaboration">

### Real-time collaboration

CKEditor Cloud Services offers a fast and highly scalable service for real-time collaboration, compatible with rich text editors built on top of the CKEditor 5 Framework. It is capable of handling real-time collaboration on text documents and tracking users connected to the document. It also serves as a storage for comments, suggestions, and revisions added to the document.

Apart from having a supporting backend to transmit operations, resolve conflicts, and apply changes between users connected to the same document, some features are needed on the client side to offer a full real-time collaboration experience:

* Showing multiple cursors and selections coming from other users.
* Showing users connecting to and disconnecting from the document.
* Offering the UI for managing comments and markers in the document.

The CKEditor Ecosystem offers a collection of plugins that can be integrated with any CKEditor 5 build to provide a fully flexible and customizable experience.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--ckeditor-5-real-time-collaboration-features">

#### CKEditor 5 Real-time collaboration features

[CKEditor 5 Real-time collaboration features](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) let you customize any CKEditor 5 integration to include real-time collaborative editing, commenting, and track changes features and tailor them to your needs.

Real-time collaboration consists of four features delivered as separate plugins that can be used with any CKEditor 5 build:

* [Real-time collaborative editing](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) – Allows for editing the same document by multiple users simultaneously. It also automatically solves all conflicts if users make changes at the same time.
* [Real-time collaborative comments](#ckeditor5/latest/features/collaboration/comments/comments.html) – Makes it possible to add comments to any part of the content in the editor.
* [Real-time collaborative track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Changes to the content are saved as suggestions that can be accepted or discarded later.
* [Real-time collaborative revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) – Multiple versions of the document are available, an older version can be restored.
* [Users selection and presence list](#ckeditor5/latest/features/collaboration/users.html) – Shows the selection of other users and lets you view the list of users currently editing the content in the editor.

All of the above features are customizable. This makes implementing real-time collaborative editing within your application a highly customizable out-of-the-box experience.

For an introduction to CKEditor 5 Collaboration Features refer to the [Collaboration overview](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html).

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--export-features">

### Export features

CKEditor Cloud Services offers a fast and highly scalable service enabling the user to export documents either to a Microsoft Word document or to a PDF document. Both of these are available as a service, making it possible to feed the data straight into the Cloud Services server for more advanced use or as convenient WYSIWYG editor plugins for ease of use in less demanding cases.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--export-to-pdf">

#### Export to PDF

The Export to PDF converter provides an API for converting HTML documents to PDF files. The service generates a file and returns it to the user so they can save it in the `.pdf` format on their disk. This allows you to easily turn your content into the portable final PDF format file collection. Available both [as a service endpoint](#cs/latest/guides/export-to-pdf/overview.html) (a premium feature) and [as a plugin](#ckeditor5/latest/features/converters/export-pdf.html) (needs to be added to the editor separately).

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--export-to-word">

#### Export to Word

The Export to Word converter provides an API for converting HTML documents to Microsoft Word `.docx` files. The service generates a Word file and returns it to the user so they can save it in the `.docx` format on their disk. This allows you to easily export your content to the Microsoft Word format. Available both [as a service endpoint](#cs/latest/guides/export-to-word/overview.html) (a premium feature) and [as a plugin](#ckeditor5/latest/features/converters/export-word.html) (needs to be added to the editor separately).

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--import-from-word">

### Import from Word

The Import from Word converter is a fast and highly scalable service enabling the user to import documents from a Microsoft Word `.docx` file. The feature is available as a service, making it possible to send a `.docx` file [straight into the Cloud Services server](#cs/latest/guides/import-from-word/overview.html) for more advanced use or as a convenient [CKEditor 5 WYSIWYG editor plugin](#ckeditor5/latest/features/converters/import-word/import-word.html) for the ease of use in less demanding cases.

The DOCX to HTML converter provides an API for converting Microsoft Word `.docx` files to HTML documents. The service generates HTML data and returns it to the user so they can save it in the HTML format on their disk.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--ckbox">

### CKBox

[CKBox](#ckbox/latest/guides/index.html) is a service that manages document assets and images. It allows for seamless uploading and management of assets within a document. The service stores them in persistent storage and provides tools to optimize image size and manage attributes, such as alternative text. Once an asset is stored, it can be reused in multiple documents.

If you plan to use it withing CKEditor 5, refer to the [CKBox plugin documentation](#ckeditor5/latest/features/file-management/ckbox.html) for details.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--cloud-region-and-on-premises-options">

### Cloud region and on-premises options

Cloud Services are available both as a cloud solution (SaaS) and as a self-hosted (on-premises) version. You can learn more about the different approaches in the dedicated [SaaS vs. On-premises](#cs/latest/guides/saas-vs-on-premises.html) guide in the Cloud Services documentation.

The cloud solution offers two regions to host your services. You can choose the [EU, US, or both cloud regions](#cs/latest/guides/saas-vs-on-premises.html--cloud-region) when working with a cloud-hosted SaaS setup.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-overview.html--next-steps">

### Next steps

* If you already use collaboration features without Real-time Collaboration you can refer to our dedicated guide about [migration of data between asynchronous and RTC editors](#cs/latest/guides/collaboration/migrating-to-rtc.html).
* If you need to save your documents in portable file formats, check out the [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) or [Export to Word](#ckeditor5/latest/features/converters/export-word.html) feature guides.
* If you need to import your documents from the `.docx` format, learn more about the [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature.
* If you are interested in the CKBox asset manager, check the [CKBox quick start](#ckbox/latest/guides/quick-start.html) guide for a short instruction on how to start using CKBox.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html">source file: "ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html"</a>

## REST API and Webhooks

<a id="ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html--cloud-services-restful-apis">

### Cloud Services RESTful APIs

CKEditor Cloud Services offer several REST APIs that can be used for server integration. They provide a lot of powerful methods that make it possible to control and manage data. They can be used to control content revisions, handle users or manage document conversions.

The APIs currently include:

* **CKEditor Cloud Services RESTful APIs** – Provides a full-featured RESTful API that you can use to create a server-to-server integration. The API documentation is available at <https://help.cke-cs.com/api/docs/>. It is an aggregator of all RESTful APIs currently available.
* **CKBox RESTful API** – Provides an API for managing data stored in the CKBox. The API documentation is available at <https://api.ckbox.io/api/docs>.
* **HTML to PDF Converter API** – Provides an API for converting HTML/CSS documents to PDF format. The API documentation is available at <https://pdf-converter.cke-cs.com/docs>.
* **HTML to DOCX Converter API** – Provides an API for converting HTML documents to Microsoft Word `.docx` files. The API documentation is available at <https://docx-converter.cke-cs.com/docs#section/Export-to-Word>
* **DOCX to HTML Converter API** – Provides an API for converting Microsoft Word `.docx`/`.dotx` files to HTML documents. The API documentation is available at <https://docx-converter.cke-cs.com/docs#section/Import-from-Word>.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html--usage">

#### Usage

Each method can be used for different purposes. For example, the REST API methods for comments allow for synchronizing comments between CKEditor Cloud Services and another system. In addition to that, CKEditor Cloud Services can be used as a database for comments because it is possible to download them via the REST API at the time they are being displayed.

An example of using another API method is getting the content of the document from a collaborative editing session. This feature can be used to build an autosave mechanism for the document, which should reduce transfer costs – autosave requests are not executed by each connected user but only by the system once at a time.

<a id="ckeditor5/latest/features/cloud-services/cloud-services-rest-api.html--webhooks">

### Webhooks

Webhooks resemble a notification mechanism that can be used to build integrations with CKEditor Cloud Services. CKEditor Cloud Services sends an HTTP POST request to a configured URL when specified events are triggered.

Webhooks can be used for data synchronization between CKEditor Cloud Services and another system or to build a notifications system. For example, thanks to webhooks, the system might notify the users via email about changes made in the document.

To learn more about CKEditor Environment webhooks, refer to the [Webhooks guide](#cs/latest/developer-resources/webhooks/overview.html) in the Cloud Services documentation.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html">source file: "ckeditor5/latest/features/cloud-services/server-side-editor-api.html"</a>

## Server-side editor API

Server-side Editor API enables deep and complex integration of your application with all document data, enabling you to manipulate content and manage collaborative data such as suggestions, comments, and revision history, and much more, directly from your server-side code (without running editor instance on the client).

The server-side editor REST API endpoint allows you to execute any JavaScript code that uses the CKEditor 5 API, that could be executed by a browser, but without a need to open the editor by a human user. Instead, the script is executed on the Cloud Services server. Please note that there are some [security-related limitations](#cs/latest/developer-resources/server-side-editor-api/security.html) for the executed JavaScript code.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--why-use-server-side-editor-api">

### Why use server-side editor API?

While CKEditor 5 provides a rich client-side editing experience, there are many scenarios where server-side content processing is essential:

* **Automation**: Run content processing tasks as part of your backend workflows.
* **Scalability**: Process multiple documents simultaneously without client-side limitations.
* **Security**: Process sensitive content in a controlled environment without exposing it to client-side manipulation.
* **Performance**: Handle large-scale content operations without impacting the user’s browser.
* **Consistency**: Ensure uniform content changes across multiple documents.
* **Integration**: Connect with other server-side systems and databases directly.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--common-use-cases">

### Common use cases

* **Deep integration**: Build custom features that can manage document content and related document data straight from your application UI, without a need to open the editor.
* **Content migration**: Restructure and update references across multiple documents, perfect for website redesigns or content reorganization.
* **Shared content blocks**: Automatically update reusable content (like headers, footers, or common sections) across all documents that use it.
* **Automated review systems**: Build systems that automatically review and suggest content changes, like grammar checks or style improvements.
* **AI-powered editing**: Make automated suggestions while users are actively editing, helping improve content quality.
* **Automated publishing**: Prepare and process content for publication, including formatting, metadata updates, and resolving comments.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--api-examples">

### API examples

Below, you will find several examples of practical server-side API applications. There are far more possibilities available.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--getting-started-with-server-side-editor-api">

#### Getting started with server-side editor API

This guide explains how to write scripts that can be executed through the Server-side Editor API endpoint. The following sections provide examples of such scripts, each demonstrating a specific use case that can be automated on the server side.

For information about setting up and using the endpoint itself, see the complementary [Cloud Services Server-side Editor API](#cs/latest/developer-resources/server-side-editor-api/editor-scripts.html) documentation.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-content">

#### Working with content

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--getting-editor-data">

##### Getting editor data

The most basic action you can perform is getting the editor data.

```
// Get the editor data.
const data = editor.getData();

// The endpoint will respond with the returned data.
return data;

```

You can also retrieve the data with specific options and include additional information about the document:

```
// Get the editor data with suggestion highlights visible.
const data = editor.getData( { showSuggestionHighlights: true } );

// Get additional document information.
const wordCount = editor.plugins.get( 'WordCount' ).getWords();

// Return both the content and metadata.
return {
    content: data,
    wordCount: wordCount
};

```

This approach allows you to not only retrieve the document content but also process it, extract metadata, or prepare it for specific use cases like exports or integrations with other systems.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--using-commands">

##### Using commands

Commands provide a high-level API to interact with the editor and change the document content. Most editor features provide a command that you can use to trigger some action on the editor.

Here is a simple example. Imagine you need to fix a typo in a company name that is spread across multiple documents. Instead of forcing the user to do it manually, you can do it with a single line of code:

```
// Replace all instances of "Cksource" with "CKSource" in the document.
editor.execute( 'replaceAll', 'CKSource', 'Cksource' );

```

This command will find all instances of “Cksource” in your documents and change them to “CKSource”. This is perfect for making bulk updates in multiple documents. Simply, execute this call for every document you would like to change.

Most CKEditor 5 features expose one or multiple commands that can be used to manipulate the editor’s state. To learn what commands are available, visit [Features guides](#ckeditor5/latest/features/index.html), and look for the “Common API” section at the end of each guide, where commands related to that feature are described.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--insert-html-content">

##### Insert HTML content

When you have HTML content ready (for example, from another system or a template), you can insert it directly into the editor. This is often simpler than building the content piece by piece using the editor API.

```
// The HTML content we want to add.
const html = '<h2>New section</h2><p>This is a <strong>new section</strong> inserted into the document using <u>server-side editor API</u>.</p>';

// Convert HTML to the editor's model.
const model = editor.data.parse( html );

// Get the root element and create an insertion position.
const root = editor.model.document.getRoot();
const insertPosition = editor.model.createPositionAt( root, 1 );

// Insert the content at the specified position.
editor.model.insertContent( model, insertPosition );

```

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--using-editor-model-api">

##### Using editor model API

If you cannot find a command that would perform a specific action on the document, you can use the editor API to apply precise changes. This approach offers the greatest flexibility and should cover any needs you may have. It requires, however, a better understanding of CKEditor internals.

For example, consider a scenario where you need to update all links in your document from `/docs/` to `/documents/`. This is a common task when moving content between environments or updating your site structure.

```
// Get the root element and create a range that covers all content.
const root = editor.model.document.getRoot();
const range = editor.model.createRangeIn( root );
const items = Array.from( range.getItems() );

editor.model.change( writer => {
    for ( const item of items ) {
        let href = item.getAttribute( 'linkHref' );

        if ( item.is( 'textProxy' ) && href ) {
            // Update the link URL.
            href = href.replace( '/docs/', '/documents/' );
            writer.setAttribute( 'linkHref', href, item );
        }
    }
} );

```

This approach is particularly useful when you have to modify the document data in some specific way, and the generic, high-level API cannot cover it.

To learn more about working with the editor engine, see the [Editing engine](#ckeditor5/latest/framework/architecture/editing-engine.html) guide.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-comments">

#### Working with comments

The [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) feature allows your users to have discussions attached to certain parts of your documents. You can use the comments feature API to implement interactions with comments with no need to open the editor itself.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--creating-comments">

##### Creating comments

You can create new comments using the `addCommentThread` command. By default, this command would create a comment thread on the current selection and create a “draft” comment thread, which might not be what you want in a server-side context. However, you can customize it using two parameters: `ranges` to specify where to place the comment, and `comment` to set its initial content.

Here is an example that shows how to automatically add comments to images that are missing the `alt` attribute:

```
const model = editor.model;
// Create a range on the whole content.
const range = model.createRangeIn( model.document.getRoot() );

editor.model.change( () => {
    // Go through each item in the editor content.
    for ( const item of range.getItems() ) {
        const isImage = item.is( 'element', 'imageBlock' ) || item.is( 'element', 'imageInline' );

        // Find images without `alt` attribute
        if ( isImage && !item.getAttribute( 'alt' ) ) {
            const commentRange = model.createRangeOn( item );
            const firstCommentMessage = 'The <u>alt</u> attribute is missing.';

            // Add a comment on the image.
            editor.execute(
                'addCommentThread',
                {
                    ranges: [ commentRange ],
                    comment: firstCommentMessage
                }
            );
        }
    }
} );

```

The above example shows how to automatically review your content and add comments where needed. You could use similar code to build automated content review systems, accessibility checkers, or any other validation workflows.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--resolving-comments">

##### Resolving comments

You can use the comments feature API to manage existing comments in your documents. For example, here is a way to resolve all comment threads in a given document:

```
// Get all comment threads from the document.
const threads = editor.plugins.get( 'CommentsRepository' ).getCommentThreads();

// Resolve all open comment threads.
for ( const thread of threads ) {
    if ( !thread.isResolved ) {
        thread.resolve();
    }
}

```

This code is particularly useful when you need to clean up a document. You might use it to automatically resolve old discussions, prepare documents for publication, or maintain a clean comment history in your content management system.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-track-changes">

#### Working with track changes

You can leverage the [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) feature API to manage existing content suggestions, retrieve final document data with all suggestions accepted, or implement automated or AI-powered content reviews.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-suggestions">

##### Working with suggestions

You can use the [track changes data plugin](../../api/module%5Ftrack-changes%5Ftrackchangesdata-TrackChangesData.html) to get the document data with all suggestions either accepted or discarded:

```
// Get the track changes data plugin.
const trackChangesData = editor.plugins.get( 'TrackChangesData' );

// Get the document data with all suggestions rejected.
// You can also use `trackChangesData.getDataWithAcceptedSuggestions()` to get data with all suggestions accepted.
const data = trackChangesData.getDataWithDiscardedSuggestions();

return data;

```

This is particularly useful when you need to show or process the “original” or the “final” document data.

While the previous example could be used to get the data, you may also want to permanently accept or discard suggestions. You can do this for all suggestions at once using the following command:

```
// Accept all suggestions in the document.
// Use `discardAllSuggestions` command to discard all suggestions instead.
editor.execute( 'acceptAllSuggestions' );

```

This command is especially helpful when finalizing documents or when working with applications where a document is split into multiple CKEditor document instances but is treated as one unit in the application. In such cases, you might, for example, want to offer a button to accept all suggestions across all document parts.

For more granular control, you can also manage individual suggestions:

```
// Get the track changes editing plugin.
const trackChangesEditing = editor.plugins.get( 'TrackChangesEditing' );

// Get a specific suggestion by its ID.
const suggestion = trackChangesEditing.getSuggestion( 'suggestion-id' );

// Accept the suggestion.
suggestion.accept();
// Or discard it.
// suggestion.discard();

```

It allows to display and manage suggestions outside the editor, for example in a separate application view where users can see all comments and suggestions and resolve them without going into the editor.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--creating-new-suggestions">

##### Creating new suggestions

Track changes is integrated with most editor commands. If you wish to change the document using commands and track these changes, all you need to do is turn on track changes mode.

Below is an example that shows a basic text replacement:

```
// Enable track changes to mark our edits as suggestions.
editor.execute( 'trackChanges' );

// Make a simple text replacement.
editor.execute( 'replaceAll', 'CKSource', 'Cksource' );

```

The `trackChanges` command ensures that all changes made by other commands are marked as suggestions.

Since Track changes feature is integrated with `Model#insertContent()` function, you can easily suggest adding some new content:

```
// Enable track changes for the new content.
editor.execute( 'trackChanges' );

// Prepare the new content to be added.
const modelFragment = editor.data.parse( 'Hello <strong>world!</strong>' );

// Add the content as a suggestion at the beginning of the document.
const firstElement = editor.model.document.getRoot().getChild( 0 );
const insertPosition = editor.model.createPositionAt( firstElement, 0 );

editor.model.insertContent( modelFragment, insertPosition );

```

Now, let’s see how to suggest deleting a specified part of the document. To do this, use `Model#deleteContent()` while in track changes mode:

```
// Enable track changes so that deleted content is marked,
// instead of being actually removed from the content.
editor.execute( 'trackChanges' );

// Get the section we want to mark as deletion suggestion.
const firstElement = editor.model.document.getRoot().getChild( 0 );

// `deleteContent()` expects selection-to-remove as its parameter.
const deleteRange = editor.model.createRangeIn( firstElement );
const deleteSelection = editor.model.createSelection( deleteRange );

// Track changes is integrated with `deleteContent()`, so the content
// will be marked as suggestion, instead of being removed from the document.
editor.model.deleteContent( deleteSelection );

```

You can use `insertContent()` and `deleteContent()` methods in the following scenarios:

* Automated suggestions based on external data.
* Creating templates that need review before finalization.
* Integrating with content management systems to propose changes.
* Building custom workflows for content creation and review.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--attribute-modifications">

##### Attribute modifications

If you wish to create attributes suggestions using the editor model API, you need to specifically tell the track changes features to record these changes. Let’s look at how to correctly make a suggestion to update links URLs:

```
// Get the track changes editing plugin for direct access to suggestion recording.
const trackChangesEditing = editor.plugins.get( 'TrackChangesEditing' );

// Get the root element and create a range that covers all content.
const root = editor.model.document.getRoot();
const range = editor.model.createRangeIn( root );
const items = Array.from( range.getItems() );

// Process each item in the document.
for ( const item of items ) {
    editor.model.change( writer => {
        // Use `recordAttributeChanges to ensure the change is properly recorded as a suggestion.
        trackChangesEditing.recordAttributeChanges( () => {
            let href = item.getAttribute( 'linkHref' );

            // Only process text proxies (parts of text nodes) that have a `linkHref` attribute.
            if ( item.is( 'textProxy' ) && href ) {
                // Update the link URL, for example changing '/docs/' to '/documents/'.
                href = href.replace( '/docs/', '/documents/' );

                // Set the new attribute value, which will be recorded as a suggestion.
                writer.setAttribute( 'linkHref', href, item );
            }
        } );
    } );
}

```

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--extracting-additional-suggestion-data">

##### Extracting additional suggestion data

Track changes feature stores and exposes more data than is saved on the Cloud Services servers. This dynamic data is evaluated by the feature on-the-fly, hence it is not stored. You can use the editor API to get access to that data.

All active suggestions have a related annotation (UI “balloon” element, located in the sidebar or displayed above the suggestion). You can, for example, retrieve a suggestion label that is displayed inside a suggestion balloon annotation.

Another useful information is content on which the suggestion was made (together with some additional context around it).

The following example demonstrates retrieving additional suggestion data:

```
const results = [];
const trackChangesUI = editor.plugins.get( 'TrackChangesUI' );
const annotations = editor.plugins.get( 'Annotations' ).collection;

// Go through all annotations available in the document.
for ( const annotation of annotations ) {
    // Check if this is a suggestion annotation.
    // Note, that another annotation type is `'comment'`.
    // You can process comments annotations to retrieve additional comments data.
    if ( annotation.type.startsWith( 'suggestion' ) ) {
        const suggestion = trackChangesUI.getSuggestionForAnnotation( annotation );

        // Get the suggestion label.
        const label = annotation.innerView.description;

        // Evaluate the content on which the suggestion was made.
        // First, get all the ranges in the content related to this suggestion.
        const ranges = [];

        // Note, that suggestions can be organized into "chains" when they
        // are next to each other. Get all suggestions adjacent to the processed one.
        for ( const adjacentSuggestion of suggestion.getAllAdjacentSuggestions() ) {
            ranges.push( ...adjacentSuggestion.getRanges() );
        }

        let contextHtml = '';

        if ( ranges.length ) {
            const firstRange = ranges[ 0 ];
            const lastRange = ranges[ ranges.length - 1 ];

            // Find the common ancestor for the whole suggestion context.
            const commonAncestor = firstRange.start.getCommonAncestor( lastRange.end );

            if ( commonAncestor ) {
                // Stringify the entire common ancestor element as HTML, highlighting suggestions.
                contextHtml = editor.data.stringify( commonAncestor, { showSuggestionHighlights: true } );
            }
        }

        results.push( {
            type: 'suggestion',
            id: suggestion.id,
            label,
            context: contextHtml
        } );
    }
}

return results;

```

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-revision-history">

#### Working with revision history

Use the [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) feature API to build more functional integration between your application and the document revisions data.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--saving-revisions">

##### Saving revisions

You can use Revision history API to save a new revision directly from your application backend:

```
// Save the current state as a new revision.
editor.plugins.get( 'RevisionTracker' ).saveRevision( { name: 'New revision' } );

```

This can be used on an unchanged document to simply create a document snapshot, or after you performed some changes to save them as a new revision.

Revision history API can help you build an automated mechanism that will automatically create revisions in some time intervals, or based on other factors. It can be particularly useful when you need to create checkpoints for your documents to maintain an audit trail of content modifications.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--working-with-revision-data">

##### Working with revision data

In more complex scenarios, you might have a need to work with content coming from various revisions of your document:

```
// Get the revision management tools.
const revisionHistory = editor.plugins.get( 'RevisionHistory' );
const revisionTracker = editor.plugins.get( 'RevisionTracker' );

// Get the latest revision from history.
const revision = revisionHistory.getRevisions()[ 0 ];

// Get the document content and document roots attributes.
const documentData = await revisionTracker.getRevisionDocumentData( revision );
const attributes = await revisionTracker.getRevisionRootsAttributes( revision );

return { documentData, attributes };

```

This is useful if you need particular revision data for further processing. It will allow you build custom backend features based on revisions, like previewing revisions data outside of editor, exporting a particular revision to PDF, or integrating revisions data with external systems.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--custom-plugins">

### Custom plugins

Server-side editor API capabilities could be extended by creating custom plugins. Custom plugins may implement complex logic and maintain reusable functionality across multiple server-side operations. Through the editor instance, you can access custom plugin API in your server-side scripts. This approach will make your code more organized and maintainable. Using a plugin will be necessary if you need to import a class or a function from one of the CKEditor 5 packages to implement your desired functionality.

To use custom plugins in server-side executed scripts, simply add them to the editor bundle that you upload to Cloud Services. Then you can access them through the editor instance:

```
// Get your custom plugin instance.
const myPlugin = editor.plugins.get( 'MyCustomPlugin' );

// Use the plugin's API.
return myPlugin.doSomething();

```

For more information about creating custom plugins, see the [Plugins architecture](#ckeditor5/latest/framework/architecture/plugins.html) guide and the [Creating a basic plugin](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html) tutorial.

<a id="ckeditor5/latest/features/cloud-services/server-side-editor-api.html--error-handling">

### Error handling

If an error occurs while processing the script on the server side, the API will return an error message and include the specific information about the encountered problem in the `data.error` object. Additionally, a `trace_id` is returned, which allows you to look up more detailed information about the specific event on the server. This makes it easier to quickly diagnose and resolve issues based on the provided identifier.

<a id="ckeditor5/latest/features/code-blocks.html">source file: "ckeditor5/latest/features/code-blocks.html"</a>

## Code blocks

The code block feature lets you insert and edit blocks of pre-formatted code. It is perfect for presenting programming-related content in an attractive, easy-to-read form.

<a id="ckeditor5/latest/features/code-blocks.html--demo">

### Demo

Use the code block toolbar button  and the type dropdown to insert a desired code block. Alternatively, start a line with a backtick, and the [autoformatting feature](#ckeditor5/latest/features/autoformat.html) will format it as a code block. To add a paragraph under a code block, simply press Enter three times.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

Each code block has a [specific programming language assigned](#ckeditor5/latest/features/code-blocks.html--configuring-code-block-languages) (like “Java” or “CSS”; this is configurable) and supports basic editing tools, for instance, [changing the line indentation](#ckeditor5/latest/features/code-blocks.html--changing-line-indentation) using the keyboard.

<a id="ckeditor5/latest/features/code-blocks.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/code-blocks.html--configuring-code-block-languages">

### Configuring code block languages

Each code block can be assigned a programming language. The language of the code block is represented as a CSS class of the `<code>` element, both when editing and in the editor data:

```
<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>

```

It is possible to configure which languages are available to the users. You can use the [codeBlock.languages](../api/module%5Fcode-block%5Fcodeblockconfig-CodeBlockConfig.html#member-languages) configuration and define your own languages. For example, the following editor supports only two languages (CSS and HTML):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        codeBlock: {
            languages: [
                { language: 'css', label: 'CSS' },
                { language: 'html', label: 'HTML' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

By default, the CSS class of the `<code>` element in the data and editing is generated using the `language` property (prefixed with “language-”). You can customize it by specifying an optional `class` property. You can set **multiple classes** but **only the first one** will be used as defining language class:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        codeBlock: {
            languages: [
                // Do not render the CSS class for the plain text code blocks.
                { language: 'plaintext', label: 'Plain text', class: '' },

                // Use the "php-code" class for PHP code blocks.
                { language: 'php', label: 'PHP', class: 'php-code' },

                // Use the "js" class for JavaScript code blocks.
                // Note that only the first ("js") class will determine the language of the block when loading data.
                { language: 'javascript', label: 'JavaScript', class: 'js javascript js-code' },

                // Python code blocks will have the default "language-python" CSS class.
                { language: 'python', label: 'Python' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/code-blocks.html--integration-with-code-highlighters">

#### Integration with code highlighters

Although live code block highlighting _**is impossible when editing**_ in CKEditor 5 ([learn more](https://github.com/ckeditor/ckeditor5/issues/436#issuecomment-548399675)), the content can be highlighted when displayed in the frontend (for example, in blog posts or website content).

The code language [configuration](../api/module%5Fcode-block%5Fcodeblockconfig-CodeBlockConfig.html#member-languages) helps to integrate with external code highlighters (for example, [highlight.js](https://highlightjs.org/) or [Prism](https://prismjs.com/)). Refer to the documentation of the highlighter of your choice and make sure the CSS classes configured in `codeBlock.languages` correspond with the code syntax autodetection feature of the highlighter.

<a id="ckeditor5/latest/features/code-blocks.html--tips-and-tweaks">

### Tips and tweaks

<a id="ckeditor5/latest/features/code-blocks.html--editing-text-around-code-blocks">

#### Editing text around code blocks

There could be situations when there is no obvious way to set the caret before or after a block of code and type. This can happen when the code block is preceded or followed by a widget (like a table) or when the code block is the first or the last child of the document (or both).

* To type **before the code block**: Put the selection at the beginning of the first line of the code block and press Enter. Move the selection to the empty line that has been created and press Enter again. A new paragraph that you can type in will be created before the code block.
* To type **after the code block**: Put the selection at the end of the last line of the code block and press Enter three times. A new paragraph that you can type in will be created after the code block.

<a id="ckeditor5/latest/features/code-blocks.html--changing-line-indentation">

#### Changing line indentation

You can change the indentation of the code using keyboard shortcuts and toolbar buttons:

* To **increase** indentation: Select the line (or lines) you want to indent. Hit the Tab key or press the “Increase indent” button in the toolbar.
* To **decrease** indentation: Select the line (or lines) the indent should decrease. Hit the Shift+Tab keys or press the “Decrease indent” button in the toolbar.

<a id="ckeditor5/latest/features/code-blocks.html--preserving-line-indentation">

#### Preserving line indentation

To speed up the editing, when typing in a code block, the indentation of the current line is preserved when you hit Enter and create a new line. If you want to change the indentation of the new line, take a look at [some easy ways to do that](#ckeditor5/latest/features/code-blocks.html--changing-line-indentation).

<a id="ckeditor5/latest/features/code-blocks.html--related-features">

### Related features

Here are some similar CKEditor 5 features that you may find helpful:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – Use the `code` formatting for short inline code chunks.
* [Block quote](#ckeditor5/latest/features/block-quote.html) – Include block quotations or pull quotes in your rich-text content.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Set indentation for text blocks such as paragraphs or lists.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the content on the go with Markdown code.

<a id="ckeditor5/latest/features/code-blocks.html--common-api">

### Common API

The [CodeBlock](../api/module%5Fcode-block%5Fcodeblock-CodeBlock.html) plugin registers:

* The `'codeBlock'` split button with a dropdown allowing to choose the language of the block.
* The ['codeBlock'](../api/module%5Fcode-block%5Fcodeblockcommand-CodeBlockCommand.html) command.  
The command converts selected WYSIWYG editor content into a code block. If no content is selected, it creates a new code block at the place of the selection.  
You can choose which language the code block is written in when executing the command. The language will be set in the editor model and reflected as a CSS class visible in the editing view and the editor (data) output:  
```  
editor.execute( 'codeBlock', { language: 'css' } );  
```  
When executing the command, you can use languages defined by the [codeBlock.languages](../api/module%5Fcode-block%5Fcodeblockconfig-CodeBlockConfig.html#member-languages) configuration. The default list of languages is as follows:  
```  
codeBlock.languages: [  
    { language: 'plaintext', label: 'Plain text' }, // The default language.  
    { language: 'c', label: 'C' },  
    { language: 'cs', label: 'C#' },  
    { language: 'cpp', label: 'C++' },  
    { language: 'css', label: 'CSS' },  
    { language: 'diff', label: 'Diff' },  
    { language: 'go', label: 'Go' },  
    { language: 'html', label: 'HTML' },  
    { language: 'java', label: 'Java' },  
    { language: 'javascript', label: 'JavaScript' },  
    { language: 'php', label: 'PHP' },  
    { language: 'python', label: 'Python' },  
    { language: 'ruby', label: 'Ruby' },  
    { language: 'typescript', label: 'TypeScript' },  
    { language: 'xml', label: 'XML' }  
]  
```

**Note**: If you execute the command with a specific `language` when the selection is anchored in a code block, and use the additional `forceValue: true` parameter, it will update the language of this particular block.  
```  
editor.execute( 'codeBlock', { language: 'java', forceValue: true } );  
```

**Note**: If the selection is already in a code block, executing the command will convert the block back into plain paragraphs.
* The ['indentCodeBlock'](../api/module%5Fcode-block%5Findentcodeblockcommand-IndentCodeBlockCommand.html) and ['outdentCodeBlock'](../api/module%5Fcode-block%5Foutdentcodeblockcommand-OutdentCodeBlockCommand.html) commands.  
Both commands are used by the Tab and Shift+Tab keystrokes as described in the [section about indentation](#ckeditor5/latest/features/code-blocks.html--changing-line-indentation):

  * The `'indentCodeBlock'` command is enabled when the selection is anchored anywhere in the code block and it allows increasing the indentation of the lines of code. The indentation character (sequence) is configurable using the [codeBlock.indentSequence](../api/module%5Fcode-block%5Fcodeblockconfig-CodeBlockConfig.html#member-indentSequence) configuration.
  * The `'outdentCodeBlock'` command is enabled when the indentation of any code lines within the selection can be decreased. Executing it will remove the indentation character (sequence) from these lines, as configured by [codeBlock.indentSequence](../api/module%5Fcode-block%5Fcodeblockconfig-CodeBlockConfig.html#member-indentSequence).

<a id="ckeditor5/latest/features/code-blocks.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-code-block>.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html"</a>

## Configuration of annotations

Tweaking the configuration of CKEditor 5 collaboration features is another easy way to change the behavior of the collaboration features views.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--collaboration-features-configuration">

### Collaboration features configuration

The full documentation of available configuration options can be found in the [comments feature editor configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-comments), the [track changes feature editor configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-trackChanges) and the [sidebar feature editor configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-sidebar) guides.

Note that comments configuration also applies to comments in a suggestion thread.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--comment-editor-configuration">

### Comment editor configuration

The editor used for adding and editing comments is also a CKEditor 5 instance. By default, it uses the following plugins:

* [Essentials](../../../api/module%5Fessentials%5Fessentials-Essentials.html),
* [Paragraph](../../../api/module%5Fparagraph%5Fparagraph-Paragraph.html),

These plugins allow for creating the comment content with some basic styles.

However, it is possible to extend the comment editor configuration and add some extra plugins or even overwrite the entire configuration and replace the list of plugins. You can modify the comment editor configuration by using the [comments.editorConfig](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html#member-editorConfig) property in the main editor configuration.

See the sample below to learn how to add the [Mention](../../../api/module%5Fmention%5Fmention-Mention.html) plugin to the comment editor:

Note that additional plugins need to be a part of the same package, just like the main editor plugins. By default, the `ckeditor5` package carries all open-source plugins, while the `ckeditor5-premium-plugins` one keeps all premium plugins at hand.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--sidebar-configuration">

### Sidebar configuration

The sidebar configuration allows for setting the container element for the sidebar and tuning the positioning mechanism. Check the [sidebar configuration](../../../api/module%5Fcomments%5Fconfig-AnnotationsSidebarConfig.html) API documentation for all available options.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--example-of-use">

#### Example of use

```
// ...

const editorConfig = {
    // ...

    comments: {
        // Show the first comment and the two most recent comments when collapsed.
        maxCommentsWhenCollapsed: 3,
        // Make comments shorter when collapsed.
        maxCommentCharsWhenCollapsed: 100,
        // Allow for up to 3 comments before collapsing.
        maxThreadTotalWeight: 600,

        // You may set the comments editor configuration.
        // In this case, use the default configuration.
        editorConfig: {}
    },
    sidebar: {
        container: document.querySelector( '#sidebar' ),
        preventScrollOutOfView: true
    },

    // ...
};

ClassicEditor.create( editorConfig );

```

Using the [comments.CommentThreadView](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html#member-CommentThreadView) and [comments.CommentView](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html#member-CommentView) configuration options is described in the [Annotations custom view](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html) guide.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--custom-date-format">

### Custom date format

The comments feature allows you to set a custom date format for comments and suggestions. To enable that, pass a function to the [locale.dateTimeFormat](../../../api/module%5Fcollaboration-core%5Fconfig-LocaleConfig.html#member-dateTimeFormat) property in the main editor configuration. This function is invoked with one argument: a comment or suggestion creation date.

```
// You can use any other library, like moment.js.
import { DateTime } from 'luxon';

// ...

const editorConfig = {
    // ...

    locale: {
        dateTimeFormat: date => DateTime.fromJSDate( date ).toFormat( 'dd/LL/yyyy' )
    }

    // ...
};

ClassicEditor.create( editorConfig );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html"</a>

## Custom template for annotations

A custom template is a middle ground between the default UI and a completely custom UI of your own.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--how-it-works">

### How it works

This solution lets you alter the HTML structure of comment and suggestion annotations. Thanks to that you can, for example:

* Add new CSS classes or HTML elements to enable more complex styling.
* Re-arrange annotation views.
* Add new UI elements, linked with your custom features.
* Remove UI elements.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--views-for-comments-and-suggestions">

### Views for comments and suggestions

The view classes used by default by CKEditor 5 collaboration features are:

* [CommentThreadView](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fcommentthreadview-CommentThreadView.html) – Generates the UI for comment thread annotations.
* [CommentView](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fcommentview-CommentView.html) – Presents a single comment.
* [SuggestionThreadView](../../../api/module%5Ftrack-changes%5Fui%5Fview%5Fsuggestionthreadview-SuggestionThreadView.html) – Generates the UI for suggestion annotations.

These closed-source classes are exported by the `ckeditor5-premium-features` package on npm ([learn more](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--setting-up-a-sample-project)).

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--changing-the-view-template">

### Changing the view template

To use a custom view template, you need to:

1. Create a new view class by extending the default view class.
2. Provide (or extend) the template by overwriting the [getTemplate()](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fcommentview-CommentView.html#function-getTemplate) method.
3. Set your custom view class through the editor configuration. We recommend setting it in the default configuration.

Creating a custom view:

Using the custom view in the editor configuration:

```
// ...

const editorConfig = {
    // ...

    comments: {
        CommentView: MyCommentView
    },

    // ...
};

ClassicEditor.create( editorConfig );

```

Custom [comment](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html#member-CommentThreadView) and [suggestion](../../../api/module%5Ftrack-changes%5Ftrackchangesconfig-TrackChangesConfig.html#member-SuggestionThreadView) thread views can be set in a similar way:

```
// ...

const editorConfig = {
    // ...

    comments: {
        CommentThreadView: MyCommentThreadView,
    },

    trackChanges: {
        SuggestionThreadView: MySuggestionThreadView
    },

    // ...
};

ClassicEditor.create( editorConfig );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--example-adding-a-new-button">

### Example: Adding a new button

Below is an example of how you can provide a simple custom feature that requires creating a new UI element and additional styling.

The proposed feature should allow for marking some comments as important. An important comment should have a yellow border on the right.

To bring this feature, you need:

* A CSS class to change the border of an important comment.
* A button to toggle the comment model state.
* An integration between the model state and the view template.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--styling-for-an-important-comment">

#### Styling for an important comment

This step is easy. Add the following styles to the `style.css` file in your project:

```
/* style.css */

/* Yellow border for an important comment. */
.ck-comment--important {
    border-right: 3px solid hsl( 55, 98%, 48% );
}

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--creating-a-button-and-adding-it-to-the-template">

#### Creating a button and adding it to the template

In this step, you will add some new elements to the template.

Keep in mind that you do not need to overwrite the whole template. You can extend it instead.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--enabling-the-custom-view">

#### Enabling the custom view

The custom view will be enabled in editor configuration, as [shown earlier](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--changing-the-view-template).

```
// main.js

// ...

const editorConfig = {
    // ...

    comments: {
        CommentView: ImportantCommentView,
        editorConfig: {
            plugins: [ Essentials, Paragraph, Bold, Italic ]
        }
    }
};

ClassicEditor.create( editorConfig );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--live-demo">

#### Live demo

Editor output:

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--annotations-editor-output">

```

```

Threads:

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html--annotations-threads">

```

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-theme.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations-custom-theme.html"</a>

## Custom annotation theme

This is the simplest way to change the look of annotations. Using the power of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables), it is really easy to override the default design of comments. You can undo this by adding an extra `.css` file.

The image above shows you which variables are responsible for every component of the default annotation view.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-theme.html--example-of-comments-customization-with-css-variables">

### Example of comments customization with CSS variables

With the [inheritance of CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fcustom%5Fproperties#Inheritance%5Fof%5Fcustom%5Fproperties), you can change the default `:root` values of the variables in the `.ck-sidebar` scope. You can override these properties with a `.css` file or place your customizations directly into the `<head>` section of your page, but in this case, you will need to use a more specific CSS selector than `:root` (for example, `<body>`).

```
/* Change the default yellow color of the comment marker in the content to green. */
:root {
    --ck-color-comment-marker: hsl(127, 98%, 83%);
    --ck-color-comment-marker-active: hsl(127, 98%, 68%);
}

.ck-sidebar {
    --ck-color-comment-background: #ecf5f0;
    --ck-color-comment-separator: #64ca6d;
    --ck-color-comment-remove-background: #eccbcb;

    --ck-comment-content-font-family: Arial;
    --ck-comment-content-font-size: 13px;
    --ck-comment-content-font-color: #333;

    --ck-color-comment-count: #807e81;

    --ck-color-annotation-icon: #0f5c2f;
    --ck-color-annotation-info: #1eb35c;

    --ck-annotation-button-size: 0.85em;

    --ck-user-avatar-background: #239855;
}

/* You can even change the appearance of a single element. */
.ck-sidebar .ck-comment__wrapper:first-of-type {
    --ck-color-annotation-info: #8e9822;
    --ck-user-avatar-background: #8e9822;
}

```

The examples above will generate the following designs for comments:

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html"</a>

## Custom view for annotations

A custom view is the most powerful way to customize annotations. In this case, you need to provide the whole view: a template, UI elements, and any necessary behavior logic, but you can still use some of the default building blocks.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--using-base-views">

### Using base views

Providing a custom view is based on the same solution as [providing a custom template](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html). You will need to create your own class for the view. In this case, you will be interested in extending base view classes:

* [BaseCommentThreadView](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fbasecommentthreadview-BaseCommentThreadView.html) – Base view for comment thread views.
* [BaseCommentView](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fbasecommentview-BaseCommentView.html) – Base view for comment views.
* [BaseSuggestionThreadView](../../../api/module%5Ftrack-changes%5Fui%5Fview%5Fbasesuggestionthreadview-BaseSuggestionThreadView.html) – Base view for suggestion thread views.

Base view classes provide some core functionality that is necessary for the view to operate, no matter what the view looks like or what its template is.

The default view classes also extend the base view classes.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--default-view-template">

### Default view template

The default template used to create comment thread views is shown here: [CommentThreadView#getTemplate()](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fcommentthreadview-CommentThreadView.html#function-getTemplate).

The default template used to create suggestion thread views is shown here: [SuggestionThreadView#getTemplate()](../../../api/module%5Ftrack-changes%5Fui%5Fview%5Fsuggestionthreadview-SuggestionThreadView.html#function-getTemplate).

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--creating-and-enabling-a-custom-view">

### Creating and enabling a custom view

As a reminder, the code snippet below shows how to enable a custom view for CKEditor 5 collaboration features:

The only obligatory action that needs to be done in your custom view constructor is setting up a template:

```
class CustomCommentThreadView extends BaseCommentThreadView {
    constructor( ...args ) {
        super( ...args );

        this.setTemplate( {
            // Template definition here.
            // ...
        } );
    }
}

```

It is your responsibility to construct the template and all the UI elements that are needed for the view.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--reading-data-and-binding-with-template">

#### Reading data and binding with template

Your view is passed a model object that is available under the `_model` property. It should be used to set (or bind to) the initial data of your view’s properties.

Some of your view’s properties may be used to control the view template. For example, you can bind a view property so that when it is set to `true`, the template main element will receive an additional CSS class. To bind view properties with a template, the properties need to be [observable](../../../api/module%5Futils%5Fobservablemixin-Observable.html#function-set:KEY%5FVALUE). Of course, you can bind already existing observable properties with your template.

You can [bind two observable properties](../../../api/module%5Futils%5Fobservablemixin-Observable.html#function-bind:SINGLE%5FBIND) in a way that the value of one property will depend on the other. You can also directly [listen to the changes of an observable property](../../../api/module%5Futils%5Fobservablemixin-Observable.html#event-change:%7Bproperty%7D).

```
const bind = this.bindTemplate;

// Set an observable property.
this.set( 'isImportant', false );

// More code.
// ...

this.setTemplate( {
    tag: 'div',

    attributes: {
        class: [
            // Bind the new observable property with the template.
            bind.if( 'isImportant', 'ck-comment--important' ),
            // Bind an existing observable property with the template.
            bind.if( 'isDirty', 'ck-comment--unsaved' )
        ]
    }
} );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--performing-actions">

#### Performing actions

The view needs to communicate with other parts of the system. When a user performs an action, something needs to be executed, for example: a comment should be removed. This communication is achieved by firing events (with appropriate data). See the example below:

```
this.removeButton = new ButtonView();
this.removeButton.on( 'execute', () => this.fire( 'removeCommentThread' ) );

```

The list of all events that a given view class can fire is available in the [API documentation of the BaseCommentThreadView class](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fbasecommentthreadview-BaseCommentThreadView.html).

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--example-comment-thread-actions-dropdown">

### Example: Comment thread actions dropdown

In this example, you will create a custom comment thread view with action buttons (edit, remove) moved to a dropdown UI element. The dropdown will be added inside a new element, and placed above the thread UI.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--creating-a-custom-thread-view-with-a-new-template">

#### Creating a custom thread view with a new template

First, create a foundation for your custom solution:

Then, you need to create a dropdown UI element and fill it with items:

Note that the dropdown should not be visible if the current local user is not the author of the thread.

Since the first comment in the comment thread represents the whole thread, you can base it on the properties of the first comment.

If there are no comments in the thread, it means that this is a new thread so the local user is the author.

```
class CustomCommentThreadView extends BaseCommentThreadView {
    constructor( ...args ) {
        super( ...args );

        const bind = this.bindTemplate;

        // The template definition is partially based on the default comment thread view.
        const templateDefinition = {
            tag: 'div',

            attributes: {
                class: [
                    'ck',
                    'ck-thread',
                    'ck-reset_all-excluded',
                    'ck-rounded-corners',
                    bind.if( 'isActive', 'ck-thread--active' )
                ],
                // Needed for the native DOM Tab key navigation.
                tabindex: 0,
                role: 'listitem',
                'aria-label': bind.to( 'ariaLabel' ),
                'aria-describedby': this.ariaDescriptionView.id
            },

            children: [
                {
                    tag: 'div',
                    attributes: {
                        class: 'ck-thread__container'
                    },
                    children: [
                        this.commentsListView,
                        this.commentThreadInputView
                    ]
                }
            ]
        };

        const isNewThread = this.length == 0;
        const isAuthor = isNewThread || this._localUser == this._model.comments.get( 0 ).author;

        // Add the actions dropdown only if the local user is the author of the comment thread.
        if ( isAuthor ) {
            templateDefinition.children.unshift(
                {
                    tag: 'div',
                    attributes: {
                        class: 'ck-thread-top-bar'
                    },

                    children: [
                        this._createActionsDropdown()
                    ]
                }
            );
        }

        this.setTemplate( templateDefinition );
    }

    // ...
}

```

As far as disabling the UI is concerned, the actions in the dropdown should be disabled if the comment thread is in the read-only mode. Also, the edit button should be hidden if there are no comments in the thread. Additionally, the resolve/reopen button should be displayed based on the comment thread resolve state.

```
// main.js

class CustomCommentThreadView extends BaseCommentThreadView {
    // ...

    _createActionsDropdown() {
        // ...

        const editButtonModel = new UIModel( {
            withText: true,
            label: 'Edit',
            action: 'edit'
        } );

        // The button should be enabled when the read-only mode is off.
        // So, `isEnabled` should be a negative of `isReadOnly`.
        editButtonModel.bind( 'isEnabled' )
            .to( this._model, 'isReadOnly', isReadOnly => !isReadOnly );

        // Hide the button if the thread has no comments yet.
        editButtonModel.bind( 'isVisible' )
            .to( this, 'length', length => length > 0 );

        items.add( {
            type: 'button',
            model: editButtonModel
        } );

        const resolveButtonModel = new UIModel( {
            withText: true,
            label: 'Resolve',
            action: 'resolve'
        } );

        // Hide the button if the thread is resolved or cannot be resolved.
        resolveButtonModel.bind( 'isVisible' )
            .to( this._model, 'isResolved', this._model, 'isResolvable',
                ( isResolved, isResolvable ) => !isResolved && isResolvable );

        items.add( {
            type: 'button',
            model: resolveButtonModel
        } );

        const reopenButtonModel = new UIModel( {
            withText: true,
            label: 'Reopen',
            action: 'reopen'
        } );

        // Hide the button if the thread is not resolved or cannot be resolved.
        reopenButtonModel.bind( 'isVisible' )
            .to( this._model, 'isResolved', this._model, 'isResolvable',
                ( isResolved, isResolvable ) => isResolved && isResolvable );

        items.add( {
            type: 'button',
            model: reopenButtonModel
        } );

        const removeButtonModel = new UIModel( {
            withText: true,
            label: 'Delete',
            action: 'delete'
        } );

        removeButtonModel.bind( 'isEnabled' )
            .to( this._model, 'isReadOnly', isReadOnly => !isReadOnly );

        items.add( {
            type: 'button',
            model: removeButtonModel
        } );
    }
}

```

Finally, some styling will be required for the new UI elements:

```
/* style.css */

/* ... */

.ck-thread-top-bar {
    padding: 2px 4px 3px 4px;
    background: #404040;
    text-align: right;
}

.ck-thread-top-bar .ck.ck-dropdown {
    font-size: 14px;
    width: 100px;
}

.ck-thread-top-bar .ck.ck-dropdown .ck-button.ck-dropdown__button {
    color: #000000;
    background: #EEEEEE;
}

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--linking-buttons-with-actions">

#### Linking buttons with actions

The edit button should turn the first comment into edit mode:

```
dropdownView.on( 'execute', evt => {
    const action = evt.source.action;

    if ( action == 'edit' ) {
        this.commentsListView.commentViews.get( 0 ).switchToEditMode();
    }

    // More actions.
    // ...
} );

```

The delete button should remove the comment thread.

As described earlier, your view should fire events to communicate with other parts of the system:

```
dropdownView.on( 'execute', evt => {
    const action = evt.source.action;

    if ( action == 'edit' ) {
        this.commentsListView.commentViews.get( 0 ).switchToEditMode();
    }

    if ( action == 'delete' ) {
        this.fire( 'removeCommentThread' );
    }

    if ( action == 'resolve' ) {
        this.fire( 'resolveCommentThread' );
    }

    if ( action == 'reopen' ) {
        this.fire( 'reopenCommentThread' );
    }

    if ( action == 'resolve' ) {
        this.fire( 'resolveCommentThread' );
    }

    if ( action == 'reopen' ) {
        this.fire( 'reopenCommentThread' );
    }
} );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--altering-the-first-comment-view">

#### Altering the first comment view

Your new custom comment thread view is ready.

For comment views, you will use the default comment views. However, there is one thing you need to take care of. Since you moved comment thread controls to a separate dropdown, you should hide these buttons from the first comment view.

This modification will be added in a custom comment thread view. It should not be done in a custom comment view because that would have an impact on comments in suggestion threads.

The first comment view can be obtained from the [commentsListView](../../../api/module%5Fcomments%5Fcomments%5Fui%5Fview%5Fbasecommentthreadview-BaseCommentThreadView.html#member-commentsListView) property. If there are no comments yet, you can listen to the property and apply the custom behavior when the first comment view is added.

```
// main.js

class CustomCommentThreadView extends BaseCommentThreadView {
    constructor( ...args ) {
        // More code.
        // ...

        if ( this.length > 0 ) {
            // If there is a comment when the thread is created, apply custom behavior to it.
            this._modifyFirstCommentView();
        } else {
            // If there are no comments (an empty thread was created by the user),
            // listen to `this.commentsListView` and wait for the first comment to be added.
            this.listenTo( this.commentsListView.commentViews, 'add', evt => {
                // And apply the custom behavior when it is added.
                this._modifyFirstCommentView();

                evt.off();
            } );
        }
    }

    // More code.
    // ...

    _modifyFirstCommentView() {
        // Get the first comment.
        const commentView = this.commentsListView.commentViews.get( 0 );

        // By default, the comment button is bound to the model state
        // and the buttons are visible only if the current local user is the author.
        // You need to remove this binding and make buttons for the first
        // comment always invisible.
        commentView.removeButton.unbind( 'isVisible' );
        commentView.removeButton.isVisible = false;

        commentView.editButton.unbind( 'isVisible' );
        commentView.editButton.isVisible = false;
    }
}

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--final-solution">

#### Final solution

Below you can find the final code for the created components:

```
/* style.css */

/* ... */

.ck-thread-top-bar {
    padding: 2px 4px 3px 4px;
    background: #404040;
    text-align: right;
}

.ck-thread-top-bar .ck.ck-dropdown {
    font-size: 14px;
    width: 100px;
}

.ck-thread-top-bar .ck.ck-dropdown .ck-button.ck-dropdown__button {
    color: #000000;
    background: #EEEEEE;
}

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html--live-demo">

#### Live demo

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html"</a>

## Annotations display mode

There are three built-in UIs to display comment threads and suggestion annotations: the wide sidebar, the narrow sidebar, and inline balloons. You can also display them together in more advanced scenarios where various annotation sources (comments, suggestions) are connected to different UIs, or even create your own UI for annotations.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--inline-balloons">

### Inline balloons

Inline balloon display mode is designed for narrow screens like mobile devices and UIs where the WYSIWYG editor is used to edit a small part of the content.

Inline display mode is the default solution. It is used when the sidebar configuration is not specified.

Even if the sidebar configuration is set, you can still dynamically switch to the inline display mode by calling the [switchTo()](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUIs.html#function-switchTo) method with the `'inline'` argument:

```
// ...

ClassicEditor
    .create( editorConfig )
    .then( editor => {
        editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'inline' );

        // The sidebar container is not removed automatically,
        // so it is up to your integration to hide it (or manage in another way).
        document.querySelector( '.editor-container__sidebar' ).style.display = 'none';
    } );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--wide-sidebar">

### Wide sidebar

The wide sidebar can fit the largest amount of information. In this mode the user can see the beginning and the end of each discussion, as well as the entire discussion for the currently selected marker. It is the recommended solution whenever you have enough space for it.

To use the wide sidebar for displaying comments and suggestion annotations, first, prepare a proper HTML structure:

```
<!DOCTYPE HTML>
<html>
    <head>
        <meta charset="utf-8" />
        <title>CKEditor 5 Sample</title>
    </head>
    <body>
        <div class="main-container">
            <div class="editor-container editor-container--classic-editor editor-container--include-annotations" id="editor-container">
                <div class="editor-container__editor-wrapper">
                    <div class="editor-container__editor"><div id="editor"></div></div>
                    <div class="editor-container__sidebar"><div id="editor-annotations"></div></div>
                </div>
            </div>
        </div>
        <script type="module" src="./main.js"></script>
    </body>
</html>

```

Then update CSS styles to display the sidebar on the right side of the editor:

```
.editor-container {
    --ckeditor5-preview-sidebar-width: 270px;
}

.editor-container__editor-wrapper {
    display: flex;
    width: fit-content;
}

.editor-container--classic-editor .editor-container__editor {
    min-width: 795px;
    max-width: 795px;
}

.editor-container__sidebar {
    min-width: var(--ckeditor5-preview-sidebar-width);
    max-width: var(--ckeditor5-preview-sidebar-width);
    margin-top: 28px;
    margin-left: 10px;
    margin-right: 10px;
}

```

Then, initialize the rich text editor. In the configuration, set the editor to use the `<div id="editor-annotations">` element as the comments container.

```
// ...

const editorConfig = {
    // ...

    sidebar: {
        container: document.querySelector('#editor-annotations')
    },

    // ...
}

ClassicEditor.create( editorConfig );

```

After setting the configuration as shown in the example above, the wide sidebar display mode will be used. If the display mode was changed, you can change it back by calling [switchTo()](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUIs.html#function-switchTo):

```
ClassicEditor
    .create( editorConfig )
    .then( editor => {
        editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'wideSidebar' );
    } );

```

You can also set the sidebar container dynamically using the [setContainer()](../../../api/module%5Fcomments%5Fannotations%5Fsidebar-Sidebar.html#function-setContainer) method:

```
ClassicEditor
    .create( editorConfig )
    .then( editor => {
        editor.plugins.get( 'Sidebar' ).setContainer( element );
    } );

```

If the sidebar container has already been set, all the items inside it will be moved to the new container.

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--narrow-sidebar">

### Narrow sidebar

The narrow sidebar is a compromise between the wide sidebar and the inline balloons. It does not take as much space as the wide sidebar but contains more information than inline annotations. The user will immediately see when multiple comment threads are added to the same spot as well as how many comments are added.

The HTML structure for the wide and narrow sidebars is similar. The only difference is that you need to set a different `min-width` CSS property for the `#editor-annotations` element:

```
/* ... */

.editor-container__sidebar {
    min-width: 65px;
}

/* ... */

```

Then, initialize the editor and switch the UI to the `narrowSidebar` mode using the [switchTo()](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUIs.html#function-switchTo) method. Note that you need to switch the UI type manually since the wide sidebar will be displayed by default.

```
// ...

const editorConfig = {
    // ...

    sidebar: {
        container: document.querySelector('#editor-annotations')
    },

    // ...
}

ClassicEditor
    .create( editorConfig )
    .then( editor => {
        editor.plugins.get( 'AnnotationsUIs' ).switchTo( 'narrowSidebar' );
    } );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--multiple-uis">

### Multiple UIs

Annotations were designed to support displaying various annotations UIs at the same time. This allows you to display different annotation sources in various places, for example, displaying comments in the wide sidebar while showing inline balloons for suggestions.

To activate multiple UIs at the same time, the filtering function should be passed to the [activate()](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUIs.html#function-activate) method. The function specifies which annotations are controlled by a given UI. Note that one annotation cannot be managed by multiple [AnnotationsUI](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUI.html) at the same time. If an annotation is not accepted by any of annotations UIs, then that annotation will not be shown.

To use a combination of annotations UIs for displaying comments and suggestion annotations, first prepare a proper HTML structure (for demonstration purposes, the wide sidebar is used):

```
<html>
    <head>
        <style type="text/css">
          #container {
                display: flex;
                position: relative;
            }

            #container .ck.ck-editor {
                width: 100%;
                max-width: 700px;
            }

            #sidebar {
                min-width: 300px;
                padding: 0 10px;
            }
        </style>
    </head>
    <body>
        <div id="container">
            <div id="editor"></div>
            <div id="sidebar"></div>
        </div>
    </body>
</html>

```

Then, initialize the rich text editor using a preset that includes both the comments and track changes features. You can get the necessary code from the [track changes integration](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html) guide. Then tweak the code to use two annotations UIs as shown below:

```
// ...

ClassicEditor
    .create( editorConfig )
    .then( editor => {
        const annotationsUIs = editor.plugins.get( 'AnnotationsUIs' );

        // Deactivate all UIs first as the `activate()` method might not deactivate all UIs.
        annotationsUIs.deactivateAll();

        annotationsUIs.activate( 'wideSidebar', annotation => annotation.type === 'comment' );
        annotationsUIs.activate( 'inline', annotation => annotation.type !== 'comment' );
    } );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--all-display-modes-in-action">

### All display modes in action

The code snippet below allows for switching between all available display modes.

In the `index.html` file obtained from the Builder, add the following markup:

```
<body>
    <!-- ... -->
    <div class="buttons">
        <button id="inline">Inline</button>
        <button id="narrow">Narrow sidebar</button>
        <button id="wide">Wide sidebar</button>
        <button id="wide-inline">Wide sidebar + inline</button>
    </div>
    <!-- ... -->
</body>

```

Then, in the `style.css` file, add the following styles

```
.editor-container__sidebar {
    transition: min-width .4s ease-out-in;
}

.editor-container__sidebar.narrow {
    min-width: 65px;
}

.editor-container__sidebar.hidden {
    display: none;
}

```

Finally, add the following code in the `main.js` file:

```
ClassicEditor
    .create( editorConfig )
    .then( editor => {
        const annotationsUIs = editor.plugins.get( 'AnnotationsUIs' );
        const annotationsContainer = document.querySelector( '.editor-container__sidebar' );
        const inlineButton = document.querySelector( '#inline' );
        const narrowButton = document.querySelector( '#narrow' );
        const wideButton = document.querySelector( '#wide' );
        const wideAndInlineButton = document.querySelector( '#wide-inline' );

        function markActiveButton( button ) {
            [ inlineButton, narrowButton, wideButton, wideAndInlineButton ]
                .forEach( el => el.classList.toggle( 'active', el === button ) );
        }

        function switchToInline() {
            markActiveButton( inlineButton );
            annotationsContainer.classList.remove( 'narrow' );
            annotationsContainer.classList.add( 'hidden' );
            annotationsUIs.switchTo( 'inline' );
        }

        function switchToNarrowSidebar() {
            markActiveButton( narrowButton );
            annotationsContainer.classList.remove( 'hidden' );
            annotationsContainer.classList.add( 'narrow' );
            annotationsUIs.switchTo( 'narrowSidebar' );
        }

        function switchToWideSidebar() {
            markActiveButton( wideButton );
            annotationsContainer.classList.remove( 'narrow', 'hidden' );
            annotationsUIs.switchTo( 'wideSidebar' );
        }

        function switchToWideSidebarAndInline() {
            markActiveButton( wideAndInlineButton );
            annotationsContainer.classList.remove( 'narrow', 'hidden' );

            annotationsUIs.deactivateAll();
            annotationsUIs.activate( 'wideSidebar', annotation => annotation.type === 'comment' );
            annotationsUIs.activate( 'inline', annotation => annotation.type !== 'comment' );
        }

        editor.ui.view.listenTo( inlineButton, 'click', () => switchToInline() );
        editor.ui.view.listenTo( narrowButton, 'click', () => switchToNarrowSidebar() );
        editor.ui.view.listenTo( wideButton, 'click', () => switchToWideSidebar() );
        editor.ui.view.listenTo( wideAndInlineButton, 'click', () => switchToWideSidebarAndInline() );

        // Set wide sidebar as default.
        switchToWideSidebar();
    } )
    .catch( error => console.error( error ) );

```

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--demo">

#### Demo

The following sample showcases the snippet above:

<a id="ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html--custom-ui">

### Custom UI

In addition to the built-in annotations UIs, it is also possible to create a custom UI that will display annotations in a way that is better suited to your application.

Note that annotations UI should implement the [AnnotationsUI](../../../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUI.html) interface.

The frame of an annotations UI is presented below. For this to work, it must be included in the list of editor plugins and activated. These are the changes that you will have to make to the `main.js` file of your project:

<a id="ckeditor5/latest/features/collaboration/annotations/annotations.html">source file: "ckeditor5/latest/features/collaboration/annotations/annotations.html"</a>

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

<a id="ckeditor5/latest/features/collaboration/annotations/annotations.html--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)](#ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html).
* [Customize annotations created by comments and track changes plugins](#ckeditor5/latest/features/collaboration/annotations/annotations.html--annotations-customization).
* Provide custom annotations for your plugins.
* Provide custom UI for annotations (for example, a custom sidebar with your display logic).

<a id="ckeditor5/latest/features/collaboration/annotations/annotations.html--annotations-customization">

### Annotations customization

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

* [Theme customization](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-theme.html).
* [Configuration, including comment input field configuration](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html).
* [Providing a custom template for the default views](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-template.html).
* [Providing a custom view for annotations](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html).

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

<a id="ckeditor5/latest/features/collaboration/annotations/annotations.html--api-overview">

### API overview

The main entry point for all external actions should be the [Annotations](../../../api/module%5Fcomments%5Fannotations%5Fannotations-Annotations.html) plugin. It stores [annotations](../../../api/module%5Fcomments%5Fannotations%5Fannotation-Annotation.html) for all editors and allows manipulating them.

In this example, the [Annotation plugin API](../../../api/module%5Fcomments%5Fannotations%5Fannotations-Annotations.html) 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](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--before-you-start) 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:

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.

<a id="ckeditor5/latest/features/collaboration/collaboration.html">source file: "ckeditor5/latest/features/collaboration/collaboration.html"</a>

## Collaboration overview

The CKEditor 5 architecture was designed to bring collaborative editing features where many authors can work on the same rich text documents.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--demo">

### Demo

Use the set of collaboration features in the demo below: turn on tracking changes , add comments , check the comments archive , and follow the revision history  of the document.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--available-collaboration-features">

### Available collaboration features

The collaboration capabilities are provided by three easy-to-integrate plugins delivering different features: comments, track changes, and revision history. You will find more information about each feature in the dedicated guides. You may also look at some interesting details and examples in the [Collaborative writing in CKEditor 5](https://ckeditor.com/blog/Feature-of-the-month-Collaborative-writing-in-CKEditor-5/) blog post after reading these guides.

You can use these features standalone or together, depending on the users’ needs. The collaboration can also be [either in real time or asynchronous](#ckeditor5/latest/features/collaboration/collaboration.html--real-time-vs-asynchronous-collaboration).

<a id="ckeditor5/latest/features/collaboration/collaboration.html--comments">

#### Comments

Thanks to the comments feature, the users can add sidenotes to marked fragments of the document, including text and block elements such as images. It also allows the users to discuss in threads and remove comments when they finish the discussion.

You can define where you want to store the comments data. To load and save it, you will also need to create a proper [integration with your database](#ckeditor5/latest/features/collaboration/comments/comments-integration.html). If you want to automatically synchronize the comments discussion between users, you can also use comments as a part of the real-time collaboration.

You can display comment threads in a sidebar or inline:

Moreover, you can resolve comment threads, which moves them to the archive. Note that the comments archive is enabled by default and cannot be turned off.

Refer to the [Comments](#ckeditor5/latest/features/collaboration/comments/comments.html) guide for more information.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--track-changes">

#### Track changes

The track changes feature brings automatic suggestion marking for the document as you change it. When editing the document, the user can switch to the track changes mode. All their changes will then create suggestions that they can accept or discard.

You can define where you want to store the suggestions data. To load and save it, you will also need to create a proper [integration with your database](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html). If you want to automatically synchronize the suggestions between users, you can also use track changes as a part of the real-time collaboration.

You can display suggestion annotations in a sidebar or inline:

Refer to the [Track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) guide for more information.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--revision-history">

#### Revision history

The revision history feature is a document versioning tool. It allows CKEditor 5 users to create and view the chronological revision history of their content. These versions are listed in the side panel. The preview mode allows for easy viewing of content development between revisions. You can rename, compare, and restore older revisions on the go.

Refer to the [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) guide for more information.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--real-time-vs-asynchronous-collaboration">

### Real-time vs asynchronous collaboration

There are two available collaboration modes in CKEditor 5: real-time collaboration (often referred to as RTC) and asynchronous collaboration. Both collaborative workflows allow your users to work together within a single application, without the need for third-party tools. They can either collaborate on documents asynchronously or use a real-time editor to write, review, and comment on content in live mode. You can use all available CKEditor 5 collaboration plugins in both modes.

| **Asynchronous vs real-time collaboration comparison** |                                                                                                              |                                                                                             |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Collaboration type                                     | **Asynchronous**                                                                                             | **Real-time**                                                                               |
| Workflow                                               | Sequential                                                                                                   | Simultaneous                                                                                |
| Features included                                      | Revision history, track changes, and comments.                                                               | Revision history, track changes, and comments working in real time.                         |
| Backend                                                | Custom backend provided by the customer.                                                                     | Backend provided by CKEditor in on-premises and SaaS modes.                                 |
| Conflict solving                                       | Not implemented.                                                                                             | Automatically solves all conflicts if users make changes at the same time.                  |
| Integration tasks for system developers                | Write backend endpoints to save and load data.Write frontend adapters to pass the data to backend endpoints. | Just configure tokens for the SaaS version.For on-premises, also set up the infrastructure. |

<a id="ckeditor5/latest/features/collaboration/collaboration.html--asynchronous-collaboration">

#### Asynchronous collaboration

Asynchronous collaboration is perfect for linear workflow, where users create, review, and edit content sequentially and there is no need for them to work simultaneously. It suits professional environments working on business deals, legal documents, academic research papers, contract management, and more use cases.

In this mode, a single author can work on the document, using the revision history, track changes and comments features to interact with previous and following editors. All work is done sequentially.

The asynchronous approach can be more cost-effective and it requires a less dedicated infrastructure. It also gives you full control over your data. Because you are fully responsible for loading, saving, and storing the data, it is the on-premises version by default. On the other hand, this approach requires you to maintain both frontend and backend integration code, also in a situation when the editor features are updated.

<a id="ckeditor5/latest/features/collaboration/collaboration.html--real-time-collaboration">

#### Real-time collaboration

In real-time collaboration, on the other hand, many users can work simultaneously on the same document, even on the same part of it, with no content locking. Comments and track changes are synchronized automatically between users, on the go. It automatically solves all conflicts that may occur if users make changes at the same time. The editor also lists all users currently involved in the editing process.

Thanks to this, collaborating users will not only be able to edit a rich text document at the same time but also discuss the process live in comments. They can also save revisions. This is perfect for fast-paced content-creation situations and it can still prove useful in a single-user mode, just like the asynchronous solution.

Real-time collaboration comes with a ready-to-use frontend integration and a backend solution. You can use it as SaaS with CKEditor Cloud Services or install on your machines in the on-premises version.

CKEditor provides both, so there is no need for a complicated integration. Import the plugins, fill in the editor configuration, and provide the token configuration. The on-premises solution requires some minimal extra setup.

You can still maintain control over your data. REST APIs will allow you to copy whatever data you stored on our servers and more!

Refer to the [Real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) guide for more information.

<a id="ckeditor5/latest/features/collaboration/comments/comments-archive.html">source file: "ckeditor5/latest/features/collaboration/comments/comments-archive.html"</a>

## Comments archive custom UI

By default, the comments archive dropdown panel is displayed in the toolbar by adding the `'commentsArchive'` button in the toolbar configuration. Refer to the [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) guide for more information.

In this guide, you will learn how to prepare a custom comments archive UI in your application and display it in the container of your choice.

<a id="ckeditor5/latest/features/collaboration/comments/comments-archive.html--before-you-start">

### Before you start

For the purpose of this guide, the CKEditor Cloud Services and the [real-time collaborative comments](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) feature will be used. However, the comments feature API can also be used in a similar way together with the [standalone comments](#ckeditor5/latest/features/collaboration/comments/comments-integration.html) feature.

Make sure that your editor is properly integrated with the comments feature before moving on.

<a id="ckeditor5/latest/features/collaboration/comments/comments-archive.html--preparing-the-html-structure">

### Preparing the HTML structure

In this guide, we will prepare an editor integration with a custom side panel.

There will be two tabs that will let the user switch between what is displayed in the side panel. By default, the side panel will display the editor’s regular wide sidebar. The other tab will switch the side panel content to display the resolved comments.

First, adjust the HTML structure by extending the `div.editor-container__sidebar` container:

```
<div class="main-container">

    ...

    <div class="editor-container" id="editor-container">
        <div class="editor-container__editor-wrapper">

            <div class="editor-container__editor"><div id="editor"></div></div>

            <div class="editor-container__sidebar">
                <div class="tabs">
                    <button class="tabs__item active" data-target="editor-annotations">Sidebar</button>
                    <button class="tabs__item" data-target="archive">Comments archive</button>
                </div>

                <div class="sidebar active" id="editor-annotations"></div>

                <div class="sidebar sidebar--archive" id="archive">
                    <div class="comments-archive">
                        <div class="comments-archive__list"></div>
                    </div>
                </div>
            </div>
        </div>
    </div>

    ...

</div>

```

Then add styles for the side panel:

```
<style>
    .ck.ck-toolbar_grouping {
        height: 40px;
    }

    .editor-container__sidebar {
        margin: 0;
        padding: 0;
    }

    .sidebar {
        display: none;
        font-size: 20px;
        padding: 0 10px 10px;
        border: 1px solid #ccced1;
        border-left: none;
        overflow: hidden;
        box-sizing: border-box;
        height: 0;
    }

    .sidebar.active {
        display: block;
        min-height: calc(100% - 40px);
    }

    .sidebar--archive.active {
        overflow: auto;
    }

    .comments-archive__list {
        padding: 0;
        margin: 0;
    }

    .comments-archive__list:empty:before {
        display: block;
        content: "There are no archived comment threads.";
        margin-top: 20px;
        font-size: 13px;
        text-align: center;
        font-style: italic;
        color: #555;
    }

    .comments-archive__list  > .ck-annotation-wrapper {
        margin-top: 10px;
    }

    .tabs {
        width: 100%;
        min-height: 40px;
        display: flex;
        flex-direction: row;
        align-items: center;
        border-top: 1px solid #ccced1;
    }

    .tabs__item {
        display: inline-flex;
        align-items: center;
        justify-content: center;
        cursor: pointer;
        width: 100%;
        height: 100%;
        min-height: 40px;
        border: 1px solid #ccced1;
        border-width: 0 1px;
        opacity: 0.5;
        box-sizing: border-box;
        padding: 0;
    }

    .tabs__item:first-child {
        border-left: none;
    }

    .tabs__item.active {
        background: #fff;
        opacity: 1.0;
    }
</style>

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-archive.html--implementing-the-custom-comments-archive-ui-plugin">

### Implementing the custom comments archive UI plugin

Now, create a plugin that will use the provided HTML structure and fill the comments archive container with resolved comment threads.

The behavior for the tabs will be implemented as simple DOM event listeners.

You can observe changes on the [CommentsArchiveUI#annotationViews](../../../api/module%5Fcomments%5Fcomments%5Fcommentsarchiveui-CommentsArchiveUI.html#member-annotationViews) collection to fill the comments archive tab content.

Additionally, for a better user experience, as long as the comments archive is shown in the side panel, the annotations for regular comment threads will be displayed in the inline display mode. This will give the users access to the regular comment threads data also when the archive is open.

```
class CustomCommentsArchiveUI extends Plugin {
    static get requires() {
        // We will use a property from the `CommentsArchiveUI` plugin, so add it to requires.
        return [ 'CommentsArchiveUI' ];
    }

    init() {
        this.tabs = document.querySelectorAll( '.tabs__item' );
        this.sidebars = document.querySelectorAll( '.sidebar' );

        // Switch the side panel to the appropriate tab after clicking it.
        this.tabs.forEach( item => {
            item.addEventListener( 'click', () => this.handleTabClick( item ) );
        } );

        this.initCommentsArchive();
    }

    // Switches between the active tabs.
    // Shows appropriate tab container and set the CSS classes to reflect the changes.
    handleTabClick( tabElement ) {
        if ( tabElement.classList.contains( 'active' ) ) {
            return;
        }

        const annotationsUIs = this.editor.plugins.get( 'AnnotationsUIs' );
        const targetId = tabElement.dataset.target;
        const sidebarContainer = document.getElementById( targetId );

        this.tabs.forEach( item => {
            item.classList.remove( 'active' );
        } );

        this.sidebars.forEach( item => {
            item.classList.remove( 'active' );
        } );

        tabElement.classList.add( 'active' );
        sidebarContainer.classList.add( 'active' );

        const isCommentsArchiveOpen = targetId === 'archive';

        // If the comments archive is open, switch the display mode for comments to "inline".
        //
        // This way the annotations for regular comments threads will be displayed next to them
        // when a user clicks on the comment thread marker.
        //
        // When the comments archive is closed, switch back to displaying comments annotations in the wide sidebar.
        annotationsUIs.switchTo( isCommentsArchiveOpen ? 'inline' : 'wideSidebar' );
    }

    initCommentsArchive() {
        // Container for the resolved comment threads annotations.
        const commentsArchiveList = document.querySelector( '.comments-archive__list' );

        // The `CommentsArchiveUI` plugin handles all annotation views that can be used
        // to render resolved comment threads inside the comments archive container.
        const commentsArchiveUI = this.editor.plugins.get( 'CommentsArchiveUI' );

        // First, handle the initial resolved comment threads.
        for ( const annotationView of commentsArchiveUI.annotationViews ) {
            commentsArchiveList.appendChild( annotationView.element );
        }

        // Handler to append new resolved thread inside the comments archive custom view.
        commentsArchiveUI.annotationViews.on( 'add', ( _, annotationView ) => {
            if ( !commentsArchiveList.contains( annotationView.element ) ) {
                commentsArchiveList.appendChild( annotationView.element );
            }
        } );

        // Handler to remove the element when thread has been removed or reopened.
        commentsArchiveUI.annotationViews.on( 'remove', ( _, annotationView ) => {
            if ( commentsArchiveList.contains( annotationView.element ) ) {
                commentsArchiveList.removeChild( annotationView.element );
            }
        } );
    }
}

```

Finally, add the new plugin to the editor.

```
ClassicEditor
    .create( {
        // ...
        plugins: [
            // ...
            CustomCommentsArchiveUI
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-archive.html--demo">

### Demo

Click the “add comment” button  in the toolbar to add a comment thread, then use the “tick” icon  to resolve a comment thread. Finally, you can see the resolved comment threads in the “Comments archive” tab.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html">source file: "ckeditor5/latest/features/collaboration/comments/comments-integration.html"</a>

## Integrating comments with your application

The comments feature [provides an API](../../../api/comments.html) that lets you add, remove, and update comments in the editor. To save and access all these changes in your database, you first need to integrate this feature.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--integration-methods">

### Integration methods

This guide will discuss two ways to integrate CKEditor 5 with your comments data source:

* [A simple “load and save” integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--a-simple-load-and-save-integration) using directly the `CommentsRepository` plugin API.
* [An adapter integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--adapter-integration) which updates the comments data immediately in the database when it changes in the editor.

The adapter integration is the recommended one because it gives you better control over the data.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--before-you-start">

### Before you start

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--preparing-a-custom-editor-setup">

#### Preparing a custom editor setup

To use the comments plugin, you need to prepare a custom editor setup with the asynchronous version of the comments feature included.

The easiest way to do that is by using the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). Pick a preset and start customizing your editor.

**In the “Features” section** of the Builder (2nd step), make sure to:

* turn off the “real-time” toggle next to the “Collaboration” group,
* enable the “Collaboration → Comments” feature.

Once you finish the setup, the Builder will provide you with the necessary HTML, CSS, and JavaScript code snippets. We will use those code snippets in the next step.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--setting-up-a-sample-project">

#### Setting up a sample project

Once we have a custom editor setup we need a simple JavaScript project to run it. For this, we recommend cloning the basic project template from our repository:

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/sample-project sample-project
cd sample-project
npm install

```

Then, install the necessary dependencies:

```
npm install ckeditor5
npm install ckeditor5-premium-features

```

This project template uses [Vite](https://vitejs.dev/) under the hood and contains 3 source files that we will use: `index.html`, `style.css`, and `main.js`.

It is now the time to use our custom editor setup. **Go to the “Installation” section** of the Builder and copy the generated code snippets to those 3 files.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with a license key. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

After you have successfully obtained the license key open the `main.js` file and update the `your-license-key` string with your license key.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--building-the-project">

#### Building the project

Finally, build the project by running:

```
npm run dev

```

When you open the sample in the browser you should see the WYSIWYG editor with the comments plugin. However, it still does not load or save any data. You will learn how to add data to the comments plugin later in this guide.

Let’s now dive deeper into the structure of this setup.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--basic-setups-anatomy">

#### Basic setup’s anatomy

Let’s now go through the key fragments of this basic setup.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--html-structure">

##### HTML structure

The HTML and CSS structure of the page creates two columns:

* `<div class="editor-container__editor">` is the container used by the editor.
* `<div class="editor-container__sidebar">` is the container used by the sidebar that holds the annotations (namely comments).

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--javascript">

##### JavaScript

The `main.js` file sets up the editor instance:

* Loads all necessary editor plugins (including the [Comments](../../../api/module%5Fcomments%5Fcomments-Comments.html) plugin).
* Sets the `licenseKey` configuration option.
* Sets the `sidebar.container` configuration option to the container mentioned above.
* Adds the `comment` and `commentsArchive` buttons to the editor toolbar.
* Defines the templates for the `CommentsIntegration` and `UsersIntegrations` plugins that we will use in the next steps of this tutorial.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments-api">

#### Comments API

The integration below uses the comments API. Making yourself familiar with the API may help you understand the code snippets. In case of any problems, refer to the [comments API documentation](../../../api/comments.html).

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--next-steps">

#### Next steps

We have set up a simple JavaScript project that runs a basic CKEditor 5 instance with the asynchronous version of the Comments feature. It does not yet handle loading or saving data, though. The next two sections cover the two available integration methods.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--a-simple-load-and-save-integration">

### A simple “load and save” integration

In this solution, users and comments data is loaded during the editor initialization, and comments data is saved after you finish working with the editor (for example when you submit the form containing the WYSIWYG editor).

This method is recommended if you can trust your users or if you provide additional validation of the submitted data. This way, we can make sure that the user changes their comments only.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--loading-the-data">

#### Loading the data

When the comments plugin is already included in the editor, you need to create a plugin which will initialize users and existing comments.

First, dump the users and comments data to a variable that will be available for your plugin.

If you have set up the sample project as [recommended in the “Before you start” section](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--before-you-start), open the `main.js` file and add this variable right after the imports:

```
// Application data will be available under a global variable `appData`.
const appData = {
    // Users data.
    users: [
        {
            id: 'user-1',
            name: 'Mex Haddox'
        },
        {
            id: 'user-2',
            name: 'Zee Croce'
        }
    ],

    // The ID of the current user.
    userId: 'user-1',

    // Comment threads data.
    commentThreads: [
        {
            threadId: 'thread-1',
            comments: [
                {
                    commentId: 'comment-1',
                    authorId: 'user-1',
                    content: '<p>Are we sure we want to use a made-up disorder name?</p>',
                    createdAt: new Date( '09/20/2018 14:21:53' ),
                    attributes: {}
                },
                {
                    commentId: 'comment-2',
                    authorId: 'user-2',
                    content: '<p>Why not?</p>',
                    createdAt: new Date( '09/21/2018 08:17:01' ),
                    attributes: {}
                }
            ],
            context: {
                type: 'text',
                value: 'Bilingual Personality Disorder'
            },
            unlinkedAt: null,
            resolvedAt: null,
            resolvedBy: null,
            attributes: {}
        }
    ],

    // Editor initial data.
    initialData:
        `<h2>
            <comment-start name="thread-1"></comment-start>
            Bilingual Personality Disorder
            <comment-end name="thread-1"></comment-end>
        </h2>
        <p>
            This may be the first time you hear about this made-up disorder but it actually isn’t so far from the truth.
            As recent studies show, the language you speak has more effects on you than you realize.
            According to the studies, the language a person speaks affects their cognition,
            behavior, emotions and hence <strong>their personality</strong>.
        </p>
        <p>
            This shouldn’t come as a surprise
            <a href="https://en.wikipedia.org/wiki/Lateralization_of_brain_function">since we already know</a>
            that different regions of the brain become more active depending on the activity.
            The structure, information and especially <strong>the culture</strong> of languages varies substantially
            and the language a person speaks is an essential element of daily life.
        </p>`
};

```

The Builder’s output sample already provides templates of two plugins: `UsersIntegration` and `CommentsIntegration`. Replace them with ones that read the data from `appData` and use the [Users](../../../api/module%5Fcollaboration-core%5Fusers-Users.html) and [CommentsRepository](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html) API:

```
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Users' ];
    }

    static get pluginName() {
        return 'UsersIntegration';
    }

    init() {
        const usersPlugin = this.editor.plugins.get( 'Users' );

        // Load the users data.
        for ( const user of appData.users ) {
            usersPlugin.addUser( user );
        }

        // Set the current user.
        usersPlugin.defineMe( appData.userId );
    }
}

class CommentsIntegration extends Plugin {
    static get requires() {
        return [ 'CommentsRepository', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'CommentsIntegration';
    }

    init() {
        const commentsRepositoryPlugin = this.editor.plugins.get( 'CommentsRepository' );

        // Load the comment threads data.
        for ( const commentThread of appData.commentThreads ) {
            commentsRepositoryPlugin.addCommentThread( commentThread );
        }
    }
}

```

Update the `editorConfig.root.initialData` property to use the `appData.initialData` value:

```
const editorConfig = {
    // ...

    root: {
        initialData: appData.initialData
    }

    // ...
};

```

And build the project:

```
npm run dev

```

You should now we see an editor instance with one comment thread.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--saving-the-data">

#### Saving the data

To save the comments data, you need to get it using the `CommentsRepository` API first. To do this, use the [getCommentThreads()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#function-getCommentThreads) method.

Then, use the comment threads data to save it in your database in the way you prefer. See the example below.

In `index.html` add:

```
<button id="get-data">Get data</button>

```

In `main.js` update the `ClassicEditor.create()` call with a chained `then()`:

```
ClassicEditor
    .create( /* ... */ )
    .then( editor => {
        // After the editor is initialized, add an action to be performed after a button is clicked.
        const commentsRepository = editor.plugins.get( 'CommentsRepository' );

        // Get the data on demand.
        document.querySelector( '#get-data' ).addEventListener( 'click', () => {
            const editorData = editor.data.get();
            const commentThreadsData = commentsRepository.getCommentThreads( {
                skipNotAttached: true,
                skipEmpty: true,
                toJSON: true
            } );

            // Now, use `editorData` and `commentThreadsData` to save the data in your application.
            // For example, you can set them as values of hidden input fields.
            console.log( editorData );
            console.log( commentThreadsData );
        } );
    } );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--demo">

#### Demo

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--data">

##### Data

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments-integration-console-data">

```

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments">

##### Comments

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments-integration-console-comments">

```

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--adapter-integration">

### Adapter integration

Adapter integration uses an adapter object – provided by you – to immediately save changes in comments in your data store. It is the recommended way of integrating comments with your application because it lets you handle client-server communication more securely. For example, you can check user permissions, validate sent data, or update the data with information obtained on the server side, like the comment creation date. You will see how to handle the server response in the following steps.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--implementation">

#### Implementation

First, define the adapter using the [CommentsRepository#adapter](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#member-adapter) property. [Adapter methods](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsAdapter.html) are called after the user makes a change in the comments. The adapter allows you to save the change in your database immediately. Each comment action has a separate adapter method that you should implement.

On the UI side, each change in comments is performed immediately, however, all adapter actions are asynchronous and are performed in the background. Because of this, all adapter methods need to return a `Promise`. When the promise is resolved, it means that everything went fine and a local change was successfully saved in the data store. When the promise is rejected, the editor throws a [CKEditorError](../../../api/module%5Futils%5Fckeditorerror-CKEditorError.html) error, which works nicely together with the [watchdog](#ckeditor5/latest/features/watchdog.html) feature. When you handle the server response you can decide if the promise should be resolved or rejected.

While any adapter action is being performed, a pending action is automatically added to the editor [PendingActions](../../../api/module%5Fcore%5Fpendingactions-PendingActions.html) plugin, so you do not have to worry that the editor will be destroyed before the adapter action has finished.

Now you are ready to implement the adapter.

If you have set up the sample project as [recommended in the “Before you start” section](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--before-you-start), open the `main.js` file and add this variable right after the imports:

```
// Application data will be available under a global variable `appData`.
const appData = {
    // Users data.
    users: [
        {
            id: 'user-1',
            name: 'Mex Haddox'
        },
        {
            id: 'user-2',
            name: 'Zee Croce'
        }
    ],

    // The ID of the current user.
    userId: 'user-1',

    // Editor initial data.
    initialData:
        `<h2>
            <comment-start name="thread-1"></comment-start>
            Bilingual Personality Disorder
            <comment-end name="thread-1"></comment-end>
        </h2>
        <p>
            This may be the first time you hear about this made-up disorder but it actually isn’t so far from the truth.
            As recent studies show, the language you speak has more effects on you than you realize.
            According to the studies, the language a person speaks affects their cognition,
            behavior, emotions and hence <strong>their personality</strong>.
        </p>
        <p>
            This shouldn’t come as a surprise
            <a href="https://en.wikipedia.org/wiki/Lateralization_of_brain_function">since we already know</a>
            that different regions of the brain become more active depending on the activity.
            The structure, information and especially <strong>the culture</strong> of languages varies substantially
            and the language a person speaks is an essential element of daily life.
        </p>`

};

```

The Builder’s output sample already provides templates of two plugins `UsersIntegration` and `CommentsIntegration`. Replace them with ones that read the data from `appData` and use the [Users](../../../api/module%5Fcollaboration-core%5Fusers-Users.html) and [CommentsRepository](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html) API:

```
class UsersIntegration extends Plugin {
    static get requires() {
        return ['Users'];
    }

    static get pluginName() {
        return 'UsersIntegration';
    }

    init() {
        const usersPlugin = this.editor.plugins.get( 'Users' );

        // Load the users data.
        for ( const user of appData.users ) {
            usersPlugin.addUser( user );
        }

        // Set the current user.
        usersPlugin.defineMe( appData.userId );
    }
}

class CommentsIntegration extends Plugin {
    static get requires() {
        return [ 'CommentsRepository', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'CommentsIntegration';
    }

    init() {
        const commentsRepositoryPlugin = this.editor.plugins.get( 'CommentsRepository' );

        // Set the adapter on the `CommentsRepository#adapter` property.
        commentsRepositoryPlugin.adapter = {
            addComment( data ) {
                console.log( 'Comment added', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                // When the promise resolves with the comment data object, it
                // will update the editor comment using the provided data.
                return Promise.resolve( {
                    createdAt: new Date()       // Should be set on the server side.
                } );
            },

            updateComment( data ) {
                console.log( 'Comment updated', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve();
            },

            removeComment( data ) {
                console.log( 'Comment removed', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve();
            },

            addCommentThread( data ) {
                console.log( 'Comment thread added', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve( {
                    threadId: data.threadId,
                    comments: data.comments.map( ( comment ) => ( { commentId: comment.commentId, createdAt: new Date() } ) ) // Should be set on the server side.
                } );
            },

            getCommentThread( data ) {
                console.log( 'Getting comment thread', data );

                // Write a request to your database here. The returned `Promise`
                // should resolve with the comment thread data.
                return Promise.resolve( {
                    threadId: data.threadId,
                    comments: [
                        {
                            commentId: 'comment-1',
                            authorId: 'user-2',
                            content: '<p>Are we sure we want to use a made-up disorder name?</p>',
                            createdAt: new Date(),
                            attributes: {}
                        }
                    ],
                    // It defines the value on which the comment has been created initially.
                    // If it is empty it will be set based on the comment marker.
                    context: {
                        type: 'text',
                        value: 'Bilingual Personality Disorder'
                    },
                    unlinkedAt: null,
                    resolvedAt: null,
                    resolvedBy: null,
                    attributes: {},
                    isFromAdapter: true
                } );
            },

            updateCommentThread( data ) {
                console.log( 'Comment thread updated', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve();
            },

            resolveCommentThread( data ) {
                console.log( 'Comment thread resolved', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve( {
                    resolvedAt: new Date(), // Should be set on the server side.
                    resolvedBy: usersPlugin.me.id // Should be set on the server side.
                } );
            },

            reopenCommentThread( data ) {
                console.log( 'Comment thread reopened', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve();
            },

            removeCommentThread( data ) {
                console.log( 'Comment thread removed', data );

                // Write a request to your database here. The returned `Promise`
                // should be resolved when the request has finished.
                return Promise.resolve();
            }

        };
    }
}

```

Update the `editorConfig.root.initialData` property to use `appData.initialData` value:

```
const editorConfig = {
    // ...

    root: {
        initialData: appData.initialData
    },

    // ...
};

```

And build the project:

```
npm run dev

```

You should now we see an editor instance with one comment thread. Observe the browser console while you interact with the comments feature in the editor (add/remove threads and comments).

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--demo-2">

#### Demo

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments-adapter-console-data">

```

```

Since the comments adapter saves the comment changes immediately after they are performed, it is also recommended to use the [Autosave](../../../api/module%5Fautosave%5Fautosave-Autosave.html) plugin to save the editor content after each change.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--why-is-there-no-event-when-i-remove-comment-thread-markers-from-the-content">

#### Why is there no event when I remove comment thread markers from the content?

Note that no remove event is fired when you remove the marker corresponding to the comment thread. Instead, the comment thread is resolved which triggers [CommentsRepository#resolveCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#event-resolveCommentThread). This operation can be restored using undo (Cmd+Z or Ctrl+Z), which will fire [CommentsRepository#reopenCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#event-reopenCommentThread).

However, you can still remove the comment thread by using available buttons in an annotation. Remember that the removal operation cannot be undone.

<a id="ckeditor5/latest/features/collaboration/comments/comments-integration.html--comments-samples">

### Comments samples

Please visit the [ckeditor5-collaboration-samples](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master) GitHub repository to find several sample integrations of the comments feature.

<a id="ckeditor5/latest/features/collaboration/comments/comments-only-mode.html">source file: "ckeditor5/latest/features/collaboration/comments/comments-only-mode.html"</a>

## Comments-only mode

In the comments-only mode, you can create, edit, and remove comments but you are unable to change the document content.

<a id="ckeditor5/latest/features/collaboration/comments/comments-only-mode.html--enabling-comments-only-mode">

### Enabling comments-only mode

The recommended way to enable the comments-only mode is by setting proper [user permissions](#ckeditor5/latest/features/collaboration/users.html--user-permissions).

If you need to enable or disable this mode based on some other logic (different from the user permissions), you can set it using the [CommentsOnly API](../../../api/module%5Fcomments%5Fcommentsonly-CommentsOnly.html).

You can use the following editor configuration:

```
ClassicEditor
    .create( {
        commentsOnly: true,
        // More editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

You can also change the mode by setting the [CommentsOnly#isEnabled](../../../api/module%5Fcomments%5Fcommentsonly-CommentsOnly.html#member-isEnabled) property:

```
editor.plugins.get( 'CommentsOnly' ).isEnabled = true;

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-only-mode.html--demo">

### Demo

Check out the comments-only mode in action in the editor below. Please note how only the content-editing features become disabled in this mode. Other features that do not affect the content like export to Word or search (but not replace!) are still available.

<a id="ckeditor5/latest/features/collaboration/comments/comments-only-mode.html--security">

### Security

Please remember that your application should be secured both on the frontend and backend. Even though the users will not be able to introduce their changes through the editor, you should still take care of preventing such action in your backend code.

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html">source file: "ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html"</a>

## Comments outside the editor

The [comments feature API](../../../api/comments.html), together with [Context](../../../api/module%5Fcore%5Fcontext-Context.html), lets you create deeper integrations with your application. One such integration is enabling comments on non-editor form fields.

In this guide, you will learn how to add this functionality to your application. Additionally, all users connected to the form will be visible in the presence list.

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--before-you-start">

### Before you start

For the purposes of this guide, the CKEditor Cloud Services and the [real-time collaborative comments](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) will be used. However, the comments feature API can also be used in a similar way together with [standalone comments](#ckeditor5/latest/features/collaboration/comments/comments-integration.html).

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--preparing-the-context">

### Preparing the context

The goal is to enable comments on non-editor form fields, so we will need to use the context to initialize the comments feature without using the editor.

First, you need to prepare [Context](../../../api/module%5Fcore%5Fcontext-Context.html) configuration. You can refer to the [Context and collaboration features](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html) guide for more in-depth explanation:

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--preparing-the-html-structure">

### Preparing the HTML structure

When the context config is ready, it is time to prepare an HTML structure with an example form, a presence list, and a sidebar.

```
<div id="editor-presence"></div>

<div id="container">
    <div class="form">
        <div class="form-field" id="field-1" tabindex="-1">
            <label>Field 1:</label>
            <input name="field-1" type="text" value="Input 1">
            <button class="add-comment">+</button>
        </div>
        <div class="form-field" id="field-2" tabindex="-1">
            <label>Field 2:</label>
            <input name="field-2" type="text" value="Input 2">
            <button class="add-comment">+</button>
        </div>
        <div class="form-field" id="field-3" tabindex="-1">
            <label>Field 3:</label>
            <input name="field-3" type="text" value="Input 3">
            <button class="add-comment">+</button>
        </div>
        <div class="form-field" id="field-4" tabindex="-1">
            <label>Field 4:</label>
            <select name="field-4">
                <option>Option 1</option>
                <option>Option 2</option>
                <option>Option 3</option>
            </select>
            <button class="add-comment">+</button>
        </div>
        <div class="form-field" id="field-5" tabindex="-1">
            <label>Field 5:</label>
            <select name="field-5">
                <option>Option 1</option>
                <option>Option 2</option>
                <option>Option 3</option>
            </select>
            <button class="add-comment">+</button>
        </div>
        <div class="form-field" id="field-6" tabindex="-1">
            <label>Field 6:</label>
            <select name="field-6">
                <option>Option 1</option>
                <option>Option 2</option>
                <option>Option 3</option>
            </select>
            <button class="add-comment">+</button>
        </div>
    </div>

    <div id="editor-annotations"></div>
</div>

```

The form contains several fields, as shown above. Each field has a button that allows for creating a comment attached to that field. Each field is assigned a unique ID. Also, the `tabindex="-1"` attribute was added to make it possible to focus the DOM elements (and add them to the [focus trackers](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html)).

Then, style HTML as below.

```
#editor-presence {
    width: 679px;
    margin: 0 auto;
}

#container {
    display: flex;
    position: relative;
    width: 679px;
    margin: 0 auto;
}

#editor-annotations {
    width: 300px;
}

.form-field {
    padding: 8px 10px;
    margin-bottom: 20px;
    outline: none;
    margin-right: 20px;
    border: 1px solid #DDDDDD;
    border-radius: 3px;
}

.form-field.has-comment {
    background: hsl(55, 98%, 83%);
}

.form-field.active {
    background: hsl(55, 98%, 68%);
}

.form-field label {
    display: inline-block;
    width: 100px;
}

.form-field input, .form-field select {
    width: 200px;
    margin: 0px;
    padding: 0px 8px;
    height: 29px;
    background: #FFFFFF;
    border: 1px solid #DDDDDD;
    border-radius: 3px;
    box-sizing: border-box;
}

.form-field button {
    width: 29px;
    margin: 0px;
    height: 29px;
    background: #EEEEEE;
    border: 1px solid #DDDDDD;
    border-radius: 3px;
    vertical-align: top;
}

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--implementing-comments-on-form-fields">

### Implementing comments on form fields

Now, it is time to integrate comments with our custom UI. The integration will meet the following requirements:

1. It will be possible to add a comment thread to any form field.
2. The comments should be sent, received, and handled in real-time.
3. There can be just one comment thread on a non-editor form field.
4. A button click creates a comment thread or activates an existing thread.
5. There should be a visible indication that there is a comment thread on a given field.

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--creating-a-context">

#### Creating a context

First, create a context instance using the `contextConfig` defined earlier.

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--adding-a-comment-thread">

#### Adding a comment thread

To create a new comment thread attached to a form field, use [CommentsRepository#openNewCommentThread()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html).

```
Context.create( contextConfig ).then( context => {

    // ...

    document.querySelectorAll( '.form-field button' ).forEach( button => {
        const field = button.parentNode;

        button.addEventListener( 'click', () => {
            // Thread ID must be unique.
            // Use field ID + current date time to generate a unique thread ID.
            const threadId = field.id + ':' + new Date().getTime();

            commentsRepository.openNewCommentThread( {
                channelId,
                threadId,
                target: () => getAnnotationTarget( field, threadId ),
                // `context` is additional information about what the comment was made on.
                // It can be left empty but it also can be set to a custom message.
                // The value is used when the comment is displayed in comments archive.
                context: {
                    type: 'text',
                    value: getCustomContextMessage( field )
                },
                // `isResolvable` indicates whether the comment thread can become resolved.
                // Set this flag to `false` to disable the possibility of resolving given comment thread.
                // You will still be able to remove the comment thread.
                isResolvable: true
            } );
        } );
    } );

    function getCustomContextMessage( field ) {
        // This function should return the custom context value for given form field.
        // It will depend on your application.
        // Below, we assume HTML structure from this sample.
        return field.previousSibling.innerText + ' ' + field.value;
    }
} );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--handling-new-comment-threads">

#### Handling new comment threads

Define a callback that will handle comment threads added to the comments repository – both created by the local user and incoming from remote users. For that, use the [CommentsRepository#addCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#event-addCommentThread).

Note that the event name includes the context channel ID. Only comments “added to the context” will be handled.

```
Context.create( contextConfig ).then( context => {

    // ...

    // This `Map` is used to store all open threads for a given field.
    // An open thread is a non-resolved, non-removed thread.
    // Keys are field IDs, and values are arrays with all opened threads on this field.
    // Since it is possible to create multiple comment threads on the same field, this `Map`
    // is used to check if a given field has an open thread.
    const commentThreadsForField = new Map();

    commentsRepository.on( 'addCommentThread:' + channelId, ( evt, data ) => {
        handleNewCommentThread( data.threadId );
    }, { priority: 'low' } );

    function handleNewCommentThread( threadId ) {
        // Get the thread instance and the related DOM element using the thread ID.
        // Note that thread ID format is "fieldId:time".
        const thread = commentsRepository.getCommentThread( threadId );
        const field = document.getElementById( threadId.split( ':' )[ 0 ] );

        // If the thread is not attached yet, attach it.
        // This is the difference between local and remote comments.
        // Locally created comments are attached in the `openNewCommentThread()` call.
        // Remotely created comments need to be attached when they are received.
        if ( !thread.isAttached ) {
            thread.attachTo( () => thread.isResolved ? null : field );
        }

        // Add a CSS class to the field to show that it has a comment.
        field.classList.add( 'has-comment' );

        // Get all open threads for given field.
        const openThreads = commentThreadsForField.get( field.id ) || [];

        // When an annotation is created or reopened we need to bound its focus manager with the field.
        // Thanks to that, the annotation will be focused whenever the field is focused as well.
        // However, this can be done only for one annotation, so we do it only if there are no open
        // annotations for a given field.
        if ( !openThreads.length ) {
            const threadView = commentsRepository._threadToController.get( thread ).view;
            const annotation = annotations.collection.getByInnerView( threadView );

            annotation.focusableElements.add( field );
        }

        // Add new thread to open threads list.
        openThreads.push( thread );

        commentThreadsForField.set( field.id, openThreads );
    }
} );

```

When the context is initialized, there could already be some comment threads created by remote users and loaded while the editor was initialized. These comments need to be handled as well.

```
for ( const thread of commentsRepository.getCommentThreads( { channelId } ) ) {
    // Ignore threads that have been already resolved.
    if ( !thread.isResolved ) {
        handleNewCommentThread(thread.id);
    }
}

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--handling-removed-comment-threads">

#### Handling removed comment threads

You should also handle removing comment threads. To provide that, use the [CommentsRepository#removeCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-RemoveCommentThreadEvent.html). Again, note the event name.

```
Context.create( contextConfig ).then( context => {

    // ...

    commentsRepository.on( 'removeCommentThread:' + channelId, ( evt, data ) => {
        handleRemovedCommentThread( data.threadId );
    }, { priority: 'low' } );

    function handleRemovedCommentThread( threadId ) {
        // Note that thread ID format is "fieldId:time".
        const field = document.getElementById( threadId.split( ':' )[ 0 ] );
        const openThreads = commentThreadsForField.get( field.id );
        const threadIndex = openThreads.findIndex( openThread => openThread.id === threadId );

        // Remove this comment thread from the list of open comment threads for given field.
        openThreads.splice( threadIndex, 1 );

        // In `handleNewCommentThread` we bound the first comment thread annotation focus manager with the field.
        // If we are removing that comment thread, we need to handle field focus as well.
        // After removing or resolving the first thread you should field focus to the next thread's annotation.
        if ( threadIndex === 0 ) {
            const thread = commentsRepository.getCommentThread( threadId );
            const threadController = commentsRepository._threadToController.get( thread );

            // Remove the old binding between removed annotation and field.
            if ( threadController ) {
                const threadView = threadController.view;
                const annotation = annotations.collection.getByInnerView( threadView );

                annotation.focusableElements.remove( field );
            }

            const newActiveThread = commentThreadsForField[ 0 ];

            // If there other open threads, bind another annotation to the field.
            if ( newActiveThread ) {
                const newThreadView = commentsRepository._threadToController.get( newActiveThread ).view;
                const newAnnotation = annotations.collection.getByInnerView( newThreadView );

                newAnnotation.focusableElements.add( field );
            }
        }

        // If there are no more active threads the CSS classes should be removed.
        if ( openThreads.length === 0 ) {
            field.classList.remove( 'has-comment', 'active' );
        }

        commentThreadsForField.set( field.id, openThreads );
    }
} );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--handling-resolvedreopened-comment-threads">

#### Handling resolved/reopened comment threads

Handling the resolving of comment threads is significant to keep your UI up to date. To manage that, use the [CommentsRepository#resolveCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#event-resolveCommentThread) and, when the thread is opened again, [CommentsRepository#reopenCommentThread event](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html#event-reopenCommentThread). As with the previous point, note the event name.

After resolving, the comment thread is removed from the sidebar, however, you can still obtain the annotation from the `Annotations#collection` and render it in a custom comments archive UI.

```
Context.create( contextConfig ).then( context => {

    // ...

    commentsRepository.on( 'resolveCommentThread:' + channelId, ( evt, { threadId } ) => {
        handleRemovedCommentThread( threadId );
    }, { priority: 'low' } );

    commentsRepository.on( 'reopenCommentThread:' + channelId, ( evt, { threadId } ) => {
        handleNewCommentThread( threadId );
    }, { priority: 'low' } );
} );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--highlighting-an-active-form-field">

#### Highlighting an active form field

To make the UI more responsive, it is a good idea to highlight the form field corresponding to the active comment. To add this improvement, add a listener to the [CommentsRepository#activeCommentThread](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html) observable property.

```
Context.create( contextConfig ).then( context => {

    // ...

    commentsRepository.on( 'change:activeCommentThread', ( evt, propName, activeThread ) => {
        // When an active comment thread changes, remove the 'active' class from all the fields.
        document.querySelectorAll( '.form-field.active' )
            .forEach( el => el.classList.remove( 'active' ) );

        // If `activeThread` is not null, highlight the corresponding form field.
        // Handle only comments added to the context channel ID.
        if ( activeThread && activeThread.channelId == channelId ) {
            const field = document.getElementById( activeThread.id.split( ':' )[ 0 ] );

            field.classList.add( 'active' );
        }
    } );
} );

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--full-implementation">

### Full implementation

Below you can find the final solution.

This is the content of the `main.js` file:

The HTML structure and styles of the `index.html` file:

```
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>CKEditor5 Collaboration – Hello World!</title>

    <style type="text/css">
        #editor-presence {
            width: 679px;
            margin: 0 auto;
        }

        #container {
            display: flex;
            position: relative;
            width: 679px;
            margin: 0 auto;
        }

        #editor-annotations {
            width: 300px;
        }

        .form-field {
            padding: 8px 10px;
            margin-bottom: 20px;
            outline: none;
            margin-right: 20px;
            border: 1px solid #DDDDDD;
            border-radius: 3px;
        }

        .form-field.has-comment {
            background: hsl(55, 98%, 83%);
        }

        .form-field.active {
            background: hsl(55, 98%, 68%);
        }

        .form-field label {
            display: inline-block;
            width: 100px;
        }

        .form-field input, .form-field select {
            width: 200px;
            margin: 0px;
            padding: 0px 8px;
            height: 29px;
            background: #FFFFFF;
            border: 1px solid #DDDDDD;
            border-radius: 3px;
            box-sizing: border-box;
        }

        .form-field button {
            width: 29px;
            margin: 0px;
            height: 29px;
            background: #EEEEEE;
            border: 1px solid #DDDDDD;
            border-radius: 3px;
            vertical-align: top;
        }
    </style>
</head>

<body>
    <div id="editor-presence"></div>

    <div id="container">
        <div class="form">
            <div class="form-field" id="field-1" tabindex="-1">
                <label>Field 1:</label>
                <input name="field-1" type="text" value="Input 1">
                <button class="add-comment">+</button>
            </div>
            <div class="form-field" id="field-2" tabindex="-1">
                <label>Field 2:</label>
                <input name="field-2" type="text" value="Input 2">
                <button class="add-comment">+</button>
            </div>
            <div class="form-field" id="field-3" tabindex="-1">
                <label>Field 3:</label>
                <input name="field-3" type="text" value="Input 3">
                <button class="add-comment">+</button>
            </div>
            <div class="form-field" id="field-4" tabindex="-1">
                <label>Field 4:</label>
                <select name="field-4">
                    <option>Option 1</option>
                    <option>Option 2</option>
                    <option>Option 3</option>
                </select>
                <button class="add-comment">+</button>
            </div>
            <div class="form-field" id="field-5" tabindex="-1">
                <label>Field 5:</label>
                <select name="field-5">
                    <option>Option 1</option>
                    <option>Option 2</option>
                    <option>Option 3</option>
                </select>
                <button class="add-comment">+</button>
            </div>
            <div class="form-field" id="field-6" tabindex="-1">
                <label>Field 6:</label>
                <select name="field-6">
                    <option>Option 1</option>
                    <option>Option 2</option>
                    <option>Option 3</option>
                </select>
                <button class="add-comment">+</button>
            </div>
        </div>

        <div id="editor-annotations"></div>
    </div>

    <script src="main.js"></script>
</body>
</html>

```

<a id="ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html--demo">

### Demo

Click the “plus” button to add a comment.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html">source file: "ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html"</a>

## Comments walkthrough

This guide explores various functionalities related to the comments feature. It also explains how the comments feature integrates with other [editor features](#ckeditor5/latest/features/index.html).

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--comments-and-comment-threads">

### Comments and comment threads

Selecting a content fragment and pressing the toolbar button  displays an annotation in the editor. This signifies that a comment thread was initiated, however, it does not contain any comments yet. The thread is submitted upon adding the first comment, which happens when you click the “Comment” button. If you click the “Cancel” button, the comment thread will be removed.

Comment thread views are also called “annotations” or “balloons.” You can display [annotations](#ckeditor5/latest/features/collaboration/annotations/annotations.html) in one of three different display modes:

* A wide sidebar
* A narrow sidebar (as shown in this guide)
* Inline

You can read more about these modes in the [Annotations display mode](#ckeditor5/latest/features/collaboration/annotations/annotations-display-mode.html) guide.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--comment-thread-view">

### Comment thread view

Each comment in a thread is shown with its author, their picture (avatar), and the comment creation time.

The top-right corner of each comment displays actions available based on [user permissions](#ckeditor5/latest/features/collaboration/users.html--user-permissions).

The “Resolve” and “Remove” buttons next to the first comment apply to **the entire thread**. Using the “Remove” action for any following comments deletes only the selected comment.

You can add custom actions to this dropdown and create other [customizations for the comment thread view](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-view.html).

At the bottom of the annotation, there is an input field. Users can type in it to keep the discussion going. The availability of this input depends on user permissions.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--comment-thread-states">

### Comment thread states

Created comment threads can assume various states over their lifecycle.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--open">

#### Open

This is the default state of a comment thread. The thread is available in the document, with its annotation positioned next to the highlighted content. Users can discuss by adding more comments (replies) to the thread.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--resolved">

#### Resolved

After clicking the “Resolve” button, the thread becomes resolved. It is moved to the **comments archive**.

You can access a resolved thread in a dedicated dropdown . Clicking a resolved thread redirects you to the highlighted content element where the thread was initiated.

A resolved comment thread looks different from an open one. There is a yellow bar within the annotation, whose main part is the **context**:

* For textual content – This is the text on which the thread was created.
* For an image – This will be its alternative text.
* For a block element with no textual information – The bar will display the default context information “Comment was made on an element.”

You can reopen a resolved comment thread by:

* Replying to it in the comments archive.
* Clicking the “Reopen” button next to the context.

At the end of the comments list, you can see the details of when and by whom the thread was resolved. This information will disappear when you reopen the thread.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--unlinked">

#### Unlinked

When you remove the document content related to a comment thread from the document, the comment thread becomes unlinked. It is then moved to the comments archive. Since it has not been technically resolved, it does not display the usual related information.

You can still interact with the unlinked thread inside the comments archive. However, since the related content is removed, it will not be highlighted in the editor. The thread will also not reopen after adding a new comment.

You can [resolve and reopen an unlinked thread](#ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--unlinked-and-resolved) as these two states are handled separately.

An unlinked thread will be restored when its related content is restored in the document. This can happen after using undo, restoring an old revision (through the {@features/revision-history revision history feature}), or loading earlier (legacy) document data that contains the related content.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--unlinked-and-resolved">

#### Unlinked and resolved

Threads can also exist in a combined state of being both unlinked and resolved, inheriting the behavior of both states.

This means that in such a thread, you can continue the discussion, which will reopen the thread. However, the thread will not show in the document unless you restore the related content (as described above).

Since the editor handles these two states separately, a comment thread may become resolved, unlinked, and then reopened and linked in any order.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--deleted">

#### Deleted

Threads in this state have been permanently removed and you cannot restore them. You can delete a comment thread only using the UI. You must confirm this action before a comment thread is permanently deleted.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--states-relation-and-flow">

#### States’ relation and flow

If you prefer a visual representation, the following diagram illustrates the various states of a comment thread:

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--integration-with-other-features">

### Integration with other features

Certain features integrate with comment threads in non-obvious ways. Such cases are presented in the section below.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--revision-history">

#### Revision history

It is important to understand the difference between unlinked and resolved or deleted comment threads when using [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html).

1. Restoring a revision will reopen an unlinked comment thread. This is because the commented content is available again in the editor.
2. Restoring a revision will not restore a resolved or deleted comment thread. The revision history feature does not restore the comment thread state.

This is the behavior expected by the user. When the user resolves or deletes a comment thread, their motivation is that the discussion was completed or was invalid. Even if you bring back the commented content, the discussion is still concluded. The comment thread should therefore stay in the archive (or stay deleted and inaccessible).

This is different when a comment thread is archived because its related content is gone. In this case, the discussion is still relevant when the removed content is restored.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--import-from-word">

#### Import from Word

The comments feature is also integrated with the [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature. All comments from imported Word documents are shown as annotations but they are marked as “external.” This aims to differentiate them from comments created inside the editor. It also prevents confusion about the identity of the comment author and clarifies the comment’s origin.

You can mark comment threads as resolved in Word. After importing a document, such threads will appear in the editor’s comment archive as resolved. However, the details on who resolved them will not be displayed since this information is unavailable in the Word file.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--export-to-word">

#### Export to Word

After exporting the editor content to a `.docx` file using the [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature:

* All open and resolved comment threads will be preserved.
* Unlinked and deleted threads will not be available.

<a id="ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--clipboard">

#### Clipboard

Comment markers are retained in the clipboard when you cut-and-paste commented content around the document. Similarly, if you drag-and-drop part of the editor content, the comments will be moved together accordingly. This is applied to resolved comment threads as well.

Please be aware, that the comment markers will be moved only if the whole comment content was moved. If only a part of a comment was cut-and-pasted or drag-and-dropped, the comment marker will stay on the original content. This was designed to prevent confusion from duplicated comments.

If you would like to enable retaining comment markers also for copy-and-paste, you need to add an [appropriate setting](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html#member-copyMarkers) to the editor configuration.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html">source file: "ckeditor5/latest/features/collaboration/comments/comments.html"</a>

## Comments overview

The comments feature lets you add comments to any part of your content, including text, and block elements such as embedded media or images. This is a great way of communication for many authors working on the same document.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--demo">

### Demo

Test the comments feature in the editor below. Select a passage or a word you need to comment and use the toolbar button  to add a comment. Use the sidebar to check the existing ones, and delete comments or comment threads. You can also resolve threads to declutter the sidebar and find them later in the comment archive dropdown .

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

Commented content is marked as highlighted and a corresponding comment balloon is displayed in the sidebar or inline. Comments can be added, edited, deleted, and replied to, allowing the users to collaborate on the same document directly in the rich text editor. Comments threads can be either deleted or resolved. The latter provides a way to archive comments that are no longer relevant, reducing clutter and making it easier to focus on the most important feedback. Users can access the comments archive from the toolbar and use it to view and restore archived comments if necessary. It helps to simplify the feedback management process. Comments markers are [moved along with the content](#ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--clipboard) on cut-and-paste and drag-and-drop actions.

The comments feature can be used together with [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) or as a standalone plugin where the comments are saved in your application using a [custom integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html). You can read more about CKEditor 5’s collaboration features and their real-life implementations in this [dedicated blog post](https://ckeditor.com/blog/Feature-of-the-month-Collaborative-writing-in-CKEditor-5/).

A [comments-only mode](#ckeditor5/latest/features/collaboration/comments/comments-only-mode.html) is also available if you want to limit the user permissions and only allow them to add comments to the document, but not edit the content directly.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--integration">

### Integration

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--use-as-a-standalone-plugin">

#### Use as a standalone plugin

The comments plugin does not require real-time collaboration to work. If you prefer a more traditional approach to document editing, the comments can be added to CKEditor 5 just like any other plugin.

To learn how to integrate comments as a standalone plugin, refer to the [Integrating comments with your application](#ckeditor5/latest/features/collaboration/comments/comments-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--use-with-real-time-collaboration">

#### Use with real-time collaboration

If you are using the real-time collaboration feature, refer to the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--learn-more">

### Learn more

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--configuration">

#### Configuration

The configuration details for the comments feature can be found in the [CommentsConfig](../../../api/module%5Fcomments%5Fconfig-CommentsConfig.html) API reference.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-with-mentions">

#### Comments with mentions

It is possible to configure the [Mentions feature](#ckeditor5/latest/features/mentions.html) to work with the Comments feature. Here you can find a [detailed description of that process](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--comment-editor-configuration).

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-markup">

#### Comments markup

Comments are always attached to someplace in the document. To make sure that they will not be lost, the comments plugin adds some special markup to the document:

* The `<comment-start>` and `<comment-end>` tags are added if the comment starts/ends in text,
* otherwise, the following attributes are added to elements:  
  * `data-comment-start-before`,
  * `data-comment-end-after`,
  * `data-comment-start-after`,
  * `data-comment-end-before`.

Read more about the [marker-to-data conversion](../../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-markerToData) to understand what data you may expect.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--examples-of-the-possible-markup">

##### Examples of the possible markup

Comment on text:

```
<p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>

```

Comment on an image:

```
<figure class="image" data-comment-end-after="b39dd790" data-comment-start-before="b39dd790">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>
</figure>

```

If your application filters HTML content, for example, to prevent XSS, you need to make sure to leave the comments tags and attributes in place when saving the content in the database. The comment markup is necessary for further editing sessions.

If you need to display the document data without the comments, you can simply remove the comments markup from the document data:

```
<p>They are awesome.</p>

```

When launching the editor, though, make sure to include comments markup in the HTML:

```
<div id="container">
    <div id="editor">
        <p>They are <comment-start name="b39dd790"></comment-start>awesome<comment-end name="b39dd790"></comment-end>.</p>
    </div>
    <div id="sidebar"></div>
</div>

```

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--saving-the-data-with-comment-highlights">

#### Saving the data with comment highlights

By default, the data returned by `editor.getData()` contains the markup for the comments as described above. It does not provide the markup that visually shows the comment highlights in the data (similarly to how they are shown in the editor).

It is possible to change the editor output using the `showCommentHighlights` option passed in `editor.getData()`. When set, the editor output will return comments similarly to how they are present inside the editor:

```
editor.getData( { showCommentHighlights: true } );

```

Will return:

```
<p>
    <span class="ck-comment-marker">
        Foo
    </span>
    bar
</p>

```

The [export to PDF feature](#ckeditor5/latest/features/converters/export-pdf.html) can be integrated with the comment highlights as shown below:

```
{
    exportPdf: {
        // More configuration of the Export to PDF.
        // ...
        dataCallback: editor => editor.getData( {
            showCommentHighlights: true
        } )
    }
}

```

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-attributes">

#### Comments attributes

The [comments attributes](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-Comment.html#function-setAttribute) are custom data that can be set and used by features built around comments. They may be used to indicate the urgency or severity of comments, categorize them into thematic fields, and so on. You can use attributes to store your feature data with other comment data.

```
comment.setAttribute( 'isImportant', true );

```

You can group multiple values in an object, using dot notation:

```
comment.setAttribute( 'customData.type', 'image' );
comment.setAttribute( 'customData.src', 'foo.jpg' );

```

Attributes set on the comment can be accessed through the `attribute` property:

```
const isImportant = comment.attributes.isImportant;
const type = comment.attributes.customData.type;

```

You can also observe the `attributes` property or bind other properties to it:

```
myObj.bind( 'customData' ).to( comment, 'attributes', attributes => attributes.customData );

```

Whenever [setAttribute()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-Comment.html#function-setAttribute) or [removeAttribute()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-Comment.html#function-removeAttribute) is called, the `attributes` property is re-set, and observables are refreshed. Using these fires the `update` method in an adapter.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-thread-attributes">

#### Comments thread attributes

Similarly, comment thread attributes are custom data that can be set and used by features built around comments. Use it to store your feature data with other comment thread data. You can also group multiple values in an object, using dot notation:

```
commentThread.setAttribute( 'customData.isImportant', true );

```

Attributes set on the comment can be accessed through the `attribute` property:

```
const isImportant = commentThread.attributes.customData.isImportant;

```

You can also observe the `attributes` property or bind other properties to it:

```
myObj.bind( 'customData' ).to( commentThread, 'attributes', attributes => attributes.customData );

```

Whenever [setAttribute()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentThread.html#function-setAttribute) or [removeAttribute()](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentThread.html#function-removeAttribute) is called, the `attributes` property is re-set, and observables are refreshed.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--why-comment-content-is-not-stored-in-the-document-data">

#### Why comment content is not stored in the document data?

Note that the markers only store the comment thread IDs. They do not include any content for security reasons. If you stored the complete comment discussion with the editor content, a malicious user could edit it, including comments written by other authors. It would be difficult to check which changes in the comments were done by the user when saving data. You would need to analyze the whole content of the document and compare it with the previous version. Considering that both content and comments could change at the same time and they are mixed, it would be a hard task to ensure that only authorized changes were introduced. For these reasons, [adapter integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--adapter-integration) is the recommended solution.

However, if you want to save your content together with the comments data, check the [simple “load and save” integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html--a-simple-load-and-save-integration) guide which should help you.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--characters-limit">

#### Characters limit

For technical reasons, each comment in the thread has a character limit set to 65000 characters. Note that comment content is stored in the HTML format, so the HTML tags (which are invisible to the user) use up some of the character limit. If the limit is exceeded, the user interface will prevent the user from submitting the comment.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--api-overview">

#### API overview

Check the [comments API documentation](../../../api/comments.html) for detailed information about the comments API. Making yourself familiar with the API may help you understand the code snippets.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-annotations-customization">

#### Comments annotations customization

The comments annotations are highly customizable. Please refer to the [Annotation customization](#ckeditor5/latest/features/collaboration/annotations/annotations.html) guide to learn more.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-only-mode">

#### Comments-only mode

You can run the editor in the [“comments-only” mode](#ckeditor5/latest/features/collaboration/comments/comments-only-mode.html). In this mode, the user can add, edit and remove comments but is unable to edit the document content or change the document data otherwise.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-for-multiple-editors">

#### Comments for multiple editors

If your application displays multiple editors on one page, you might want to use the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html). It will, among others, let you display comments from all editors inside one sidebar.

<a id="ckeditor5/latest/features/collaboration/comments/comments.html--comments-outside-the-editor">

#### Comments outside the editor

The comments feature can be also used on regular form-fields or HTML elements. Thanks to that, you can allow for commenting on all elements of your application and provide a unified user experience and interface. See the [Comments outside the editor](#ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html) guide to learn more.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html">source file: "ckeditor5/latest/features/collaboration/context-and-collaboration-features.html"</a>

## Using context with collaboration features

The [Context class](../../api/module%5Fcore%5Fcontext-Context.html) organizes multiple editors into one environment. This way you can initialize some features not for a single editor but for its context accessible to many editors.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--introduction-to-the-context">

### Introduction to the context

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--collaboration-features-and-multiple-editors">

#### Collaboration features and multiple editors

Most applications use just one editor instance per a web page or a form. In these integrations, the editor is the topmost entity that initializes features and coordinates their work. Collaboration features such as a sidebar or presence list are linked with this single editor instance and only handle the changes happening within this editor instance.

It does not create a good user experience for applications that need to present multiple editors on one web page, though. In that case, each editor instance has its own sidebar and presence list. Also, multiple, separate connections need to be handled for data exchange.

The [Context class](../../api/module%5Fcore%5Fcontext-Context.html) was introduced to solve such issues. It organizes multiple editors into one environment. Some of the features, instead of being initialized for a singular editor, can be initialized for the whole context. Then, each editor can use the same instance of the feature, which means that there can be one common presence list or sidebar linked with multiple editors.

Note that only selected plugins are prepared to work as context plugins. See the API documentation for collaboration features to learn which plugins can be used as context plugins.

Additionally, in integrations using [Context](../../api/module%5Fcore%5Fcontext-Context.html) and multiple editor instances, each editor instance will display only “its own” comment threads in the comments archive panel.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--collaboration-features-and-no-editor">

#### Collaboration features and no editor

A context plugin that is added to a context is ready as soon as the context is created. This allows for using the context plugins without creating an editor at all!

Thanks to that you can provide features like [comments on non-editor form fields](#ckeditor5/latest/features/collaboration/comments/comments-outside-editor.html) that are no longer just editor features but are deeply integrated with your application.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--channel-id">

#### Channel ID

The channel ID is used to identify a data storage for collaboration features that a given editor or context should connect to. If you are using multiple editors, each of them must use a different channel ID to connect to a specific document. Additionally, the context itself, needs to specify its own, unique channel ID.

To set the channel ID, use the [config.collaboration.channelId](../../api/module%5Fcollaboration-core%5Fconfig-RealTimeCollaborationConfig.html#member-channelId) configuration property. See the code snippets below.

The channel ID is frequently used as a parameter or data property in the [comments API](../../api/comments.html). If you are preparing a custom integration using the comments API, you can use the channel ID to recognize whether the comment was added to an editor instance or to a context.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--before-you-start">

### Before you start

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--preparing-a-custom-editor-setup-with-the-context">

#### Preparing a custom editor setup with the context

The context can be used with both: standalone collaboration features and real-time collaboration features. Below is an example featuring real-time collaboration.

To use `Context`, add it to your editor setup:

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--using-the-context-in-an-integration">

### Using the context in an integration

After your editor setup is ready, you need to configure and initialize the context and the editor.

If you use the HTML produced by the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs), it is enough to update the content of the `.editor-container__editor` container to this:

```
<div class="editor-container__editor">
    <div id="editor1" class="editor"></div>
    <div id="editor2" class="editor"></div>
    <div id="editor3" class="editor"></div>
</div>

```

We can now setup three editor instances, sharing one context, on these elements:

```
// An example of initialization of the context and multiple editors:
Context.create( contextConfig ).then( context => {
    // After the context is ready, initialize an editor on all elements in the DOM with the `.editor` class:
    for ( const editorElement of document.querySelectorAll( '.editor' ) ) {
        // Create current editor's config based on the earlier defined template.
        const currentEditorConfig = Object.assign( editorConfig, {
            root: {
                element: editorElement
            },

            // Pass the context to the editor.
            context,

            // Each editor should connect to its document.
            // Create a unique channel ID for an editor (document).
            collaboration: {
                channelId: 'channel-id-' + editorElement.id
            }
        } );

        DecoupledEditor.create( currentEditorConfig ).then( editor => {
            // Insert the toolbar of this editor right above its editing area.
            document.querySelector( '.editor-container__editor' )
                .insertBefore( editor.ui.view.toolbar.element, editor.ui.view.editable.element );

            // You can do something with the editor instance after it was initialized.
            // ...
        } );
    }
} );

```

The demo will render three editor instances, one after another. Since they share one context, you will be able to observe that:

* The presence list is shared between them (and they use one collaboration session).
* The sidebar with comments is also shared between them.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--context-and-watchdog">

### Context and watchdog

Similarly to an editor instance, context can be integrated with a watchdog to handle the errors that may happen in the editor or context features. Please refer to the [watchdog documentation](#ckeditor5/latest/features/watchdog.html--context-watchdog) to learn how to use the context watchdog.

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--minimal-implementation">

### Minimal implementation

Below are code snippets showcasing the use of a context and a watchdog together with real-time collaboration features.

The `main.js` file:

The HTML file:

```
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>CKEditor 5 Collaboration – Hello World!</title>

    <style type="text/css">
        #presence-list-container {
            width: 800px;
            margin: 0 auto;
        }

        #container {
            display: flex;
            position: relative;
            width: 800px;
            margin: 0 auto;
        }

        .form {
            width: 500px;
        }

        #container .ck.ck-editor {
            width: 100%;
        }

        #sidebar {
            width: 300px;
            padding: 0 10px;
        }
    </style>
</head>

<body>
    <div id="presence-list-container"></div>

    <div id="container">
        <div class="form">
            <div class="editor" id="editor-1">
                <h2>Editor 1</h2>
                <p>Foo bar baz</p>
            </div>
            <div class="editor" id="editor-2">
                <h2>Editor 2</h2>
                <p>Foo bar baz</p>
            </div>
        </div>
        <div id="sidebar"></div>
    </div>

    <script type="module" src="./main.js"></script>
</body>
</html>

```

<a id="ckeditor5/latest/features/collaboration/context-and-collaboration-features.html--demo">

### Demo

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html">source file: "ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html"</a>

## Real-time collaboration feature integration

This quick start guide will let you set up real-time collaboration inside your editor, including basic integration with other collaboration features.

After reading this article, we recommend visiting the “Learn more” sections in our documentation pages for the [comments](#ckeditor5/latest/features/collaboration/comments/comments.html--learn-more), [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html--learn-more) and [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--learn-more) features to get more in-depth knowledge about them.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--sign-up-to-the-collaboration-service">

### Sign up to the collaboration service

The real-time collaboration feature needs a server to synchronize content between the clients, so to use it, you need to sign up to the collaboration service first. Refer to the [CKEditor Cloud Services Collaboration – Quick Start](#cs/latest/guides/collaboration/quick-start.html) guide for more details. There is also the [Premium features free trial](#trial/latest/index.html) available for testing purposes, that will provide the necessary backend.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--preparing-a-custom-editor-setup">

#### Preparing a custom editor setup

To use the real-time collaboration, you need to prepare a custom editor setup with several features enabled.

The easiest way to do that is by using the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). Pick a preset and start customizing your editor.

**In the “Features” section** of the Builder (2nd step), make sure to:

* make sure the “real-time” toggle next to the “Collaboration” group is on,
* pick the entire “Collaboration” feature group.

Once you finish the setup, the Builder will provide you with the necessary HTML, CSS, and JavaScript code snippets. We will use those code snippets in the next step.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--setting-up-a-sample-project">

#### Setting up a sample project

Once we have a custom editor setup we need a simple JavaScript project to run it. For this, we recommend cloning the basic project template from our repository:

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/sample-project sample-project
cd sample-project
npm install

```

Then, install the necessary dependencies:

```
npm install ckeditor5
npm install ckeditor5-premium-features

```

This project template uses [Vite](https://vitejs.dev/) under the hood and contains 3 source files that we will use: `index.html`, `style.css`, and `main.js`.

It is now the time to use our custom editor setup. **Go to the “Installation” section** of the Builder and copy the generated code snippets to those 3 files.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--configure-and-initialize-the-editor">

### Configure and initialize the editor

To finalize the editor configuration, you need to take a few additional steps in the `main.js` file:

* In the editor configuration (`editorConfig`), you need to fill in the following fields:

  * The [CKEditor Cloud Services connection data (cloudServices)](../../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html),
  * The [collaboration.channelId](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-channelid-configuration-property) value.
  * The valid `licenseKey`. Please refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.
* This example uses the [watchdog](#ckeditor5/latest/features/watchdog.html) feature that provides an additional layer of protection against data loss in case the editor crashes. Use [Watchdog.create()](../../../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html#function-create) instead of `ClassicEditor.create()` to take advantage of this feature, as shown in the example below.

```
const editorConfig = {
    /* ... */

    attachTo: document.querySelector( '#editor' ),
    licenseKey: '<YOUR_LICENSE_KEY>',
    cloudServices: {
        tokenUrl: '<YOUR_CLOUD_SERVICES_TOKEN_URL>',
        webSocketUrl: '<YOUR_CLOUD_SERVICES_WEBSOCKET_URL>'
    },
    collaboration: {
        channelId: 'your-unique-channel-per-document'
    },

    /* ... */
};

const { EditorWatchdog } = ClassicEditor;
const watchdog = new EditorWatchdog( ClassicEditor );

// Replace ClassicEditor.create(editorConfig); with
watchdog.create( editorConfig );

```

Voilà! All users who open this page should be able to collaborate, working on the same rich text document at the same time.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-channelid-configuration-property">

#### The `channelId` configuration property

The [config.collaboration.channelId](../../../api/module%5Fcollaboration-core%5Fconfig-RealTimeCollaborationConfig.html#member-channelId) configuration property is an important property that controls which editor instances collaborate with one another. All clients created with the same `channelId` will be collaborating on the same content.

Each document must have a different `channelId`. This ID is usually the primary key of the document in the database or a unique identifier for a given form field. However, you are free to provide whatever identifier fits your scenario.

The `channelId` needs to be unique in a given environment, so if you are using, for instance, staging and production environments, you may use the same channel ID in these. Since the environments are separated, these IDs will not interfere with one another.

Since editor content is linked with and only with the channel ID, it is possible to create an application where different views (forms, subpages, etc.) provide various sets of rich-text editable fields and have users collaborate with each other even though they have opened a different form, etc.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--handling-document-data">

### Handling document data

All comments, suggestions, and revisions data is saved in CKEditor Cloud Services to make the integration work out of the box.

Note that CKEditor Cloud Services does not save or load the document content. Instead, Cloud Services acts as a medium to handle the collaboration process. Content management should be handled by the application integration.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--data-initialization">

#### Data initialization

When the first user opens the rich text editor for a certain document ID, their content is sent to CKEditor Cloud Services. In case of the example above it is:

```
<p>Let's edit this together!</p>

```

If you cannot or do not want to set the initial data straight in the HTML, use the [initialData configuration option](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData) instead. Do not use [editor.setData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData) (see below).

After the first user initializes the document and starts the editing session, every other user that connects to the same document will receive the content from CKEditor Cloud Services (while their local initial data is discarded).

From that moment on, every single change to the editor content is passed between Cloud Services and clients and the document for each client is updated. Any conflicting updates are resolved on the fly.

This is the reason why you should not use the `editor.setData()` or `editor.data.set()` methods when using the collaboration plugin. These simply overwrite the whole content of the editor (even if the data to set is the same as the current editor data). In real-time collaboration, this behavior can result in overwriting other clients’ local updates. In most cases, using `editor.setData()` and `editor.data.set()` in real-time collaboration is incorrect.

If you are sure that you understand and accept the behavior and side effects of setting the editor data this way, you can call `editor.data.set()` with the flag `suppressErrorInCollaboration` set to `true`:

```
editor.data.set( '<p>Your data</p>', { suppressErrorInCollaboration: true } );

```

This will let you overwrite the editor data without throwing an error.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--saving-data">

#### Saving data

Although CKEditor Cloud Services handles passing data between clients, you are still responsible for saving the final data in your database. The document is stored in the cloud by CKEditor Cloud Services only temporarily, as long as there are connected users. It means that the editor content should be saved in the database on your server before the last user disconnects – otherwise it will be lost. It is recommended to save the data automatically whenever it changes.

CKEditor 5 provides two utilities to make your integration simpler.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-clouddocumentversion-property">

##### The `cloudDocumentVersion` property

When your collaborative users are saving the same document at the same time, there might be a conflict. It might happen that one user will try to save an older document version, overwriting a newer one.

To prevent such race conditions, use the `cloudDocumentVersion` property.

```
editor.plugins.get( 'RealTimeCollaborationClient' ).cloudDocumentVersion

```

This property is simply a number, and a bigger value means a newer document version. This number should be stored in the database together with the document content. When a client wants to save the content, document versions should be compared. The document should only be saved when the version is higher. Otherwise, it means that the incoming data is an older version of the document and should be discarded.

CKEditor Cloud Services keeps the value of `cloudDocumentVersion` and makes sure that it is properly set whenever there is a new editing session for a given document.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-autosave-plugin">

##### The `Autosave` plugin

The second helper is the [Autosave](../../../api/module%5Fautosave%5Fautosave-Autosave.html) plugin.

The autosave plugin triggers the save callback whenever the user changes the content. It takes care of throttling the callback execution to limit the number of calls to the database. It also automatically secures the user from leaving the page before the content is saved.

The autosave plugin is not enabler by default. To learn more about this plugin, refer to the [Autosave](#ckeditor5/latest/features/autosave.html) feature guide.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--autosave-for-revision-history">

##### Autosave for revision history

If you are using the revision history feature, your autosave callback should take care of updating the recent revision data. You can add the [autosave](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-autosave) configuration to `editorConfig` in the `main.js` file as shown below:

```
const editorConfig = {
    /* ... */

    autosave: {
        save: async editor => {
            const revisionTracker = editor.plugins.get( 'RevisionTracker' );
            const currentRevision = revisionTracker.currentRevision;
            const oldRevisionVersion = currentRevision.toVersion;

            // Update the current revision with the newest document changes.
            await revisionTracker.update();

            // Check if the revision was updated.
            // If not, do not make an unnecessary call.
            if ( oldRevisionVersion === currentRevision.toVersion ) {
                return true;
            }

            // Use the document data saved with the revision instead of the editor data.
            // Revision data may slightly differ from the editor data when
            // real-time collaboration is involved.
            const documentData = await revisionTracker.getRevisionDocumentData( revisionTracker.currentRevision );

            // Use revision version instead of `cloudDocumentVersion`.
            const documentVersion = currentRevision.toVersion;

            // `saveData()` should save the document in your database.
            // `documentData` contains data for all roots.
            // You can save just `documentData.main` if you are using a single root,
            // or the whole object if you are using multiple roots.
            return saveData( documentData.main, documentVersion );
        }
    },

    /* ... */
}

```

You can read more about saving revisions in the [Revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--how-revisions-are-updated-and-saved) guide.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--reconnection-process">

### Reconnection process

During the real-time collaboration, it may happen that the internet connection will go down for some time. When this happens, the editor will switch into read-only mode. After the connection is back, the real-time collaboration plugin will try to reconnect the editor back to the editing session. This reconnection process may involve re-creating the editing session (if the reconnection happens after a longer period of time).

While one client is offline, other clients may perform changes to the document. When the offline client reconnects, the real-time editing plugin will make a decision if the reconnection is possible.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--users-selection">

### Users selection

The real-time collaborative editing feature not only synchronizes the document content between all participants, but it also shows each user the list of all other users in real time. It works out of the box and does not require any additional configuration. This is the only part of the real-time collaborative editing plugin that provides a UI. Refer to the [Users in real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html) guide to learn more.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--real-time-collaboration-samples">

### Real-time collaboration samples

Please visit the [ckeditor5-collaboration-samples](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master) GitHub repository to find various sample integrations of the real-time collaboration feature.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html">source file: "ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html"</a>

## Real-time collaboration overview

The real-time collaboration features let many users simultaneously edit content, leave comments, suggest changes, and access revision history. You can include these features in any CKEditor 5 preset and tailor them to your needs.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html--demo">

### Demo

Try CKEditor 5 collaboration features in the demo below. Use the comments, track changes, and revision history toolbar items to enable each feature.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

The CKEditor 5 real-time collaboration experience is enabled by several plugins that can be added to the editor preset just like any other CKEditor 5 plugin.

These include two base, real-time-collaboration-oriented features:

* Real-time collaborative editing – Allows for editing the same document by multiple users simultaneously. It also automatically solves all conflicts if users make changes at the same time.
* [Users selection and presence list](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html) – Shows the selection of other users and lets you view the list of users currently editing the content in the editor.

We also provide plugins that integrate our other premium collaboration features with real-time editing:

* Real-time collaborative [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) – Makes it possible to add comments to any part of content in the editor.
* Real-time collaborative [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Changes to the content are saved as suggestions that can be accepted or discarded later.
* Real-time [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) – Create and view the chronological revision history of the document.

Refer to the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) guide to learn how to enable real-time collaboration in your WYSIWYG editor.

You can read more about CKEditor 5’s collaboration features and their real-life implementations in this [dedicated blog post](https://ckeditor.com/blog/Feature-of-the-month-Collaborative-writing-in-CKEditor-5/).

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html">source file: "ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html"</a>

## Users in real-time collaboration

After you [enable the real-time collaborative editing](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) plugin, the selections of collaborating users will automatically display to all of them with no additional configuration. The editor will also set the proper permissions for the local user based on data received from the server.

There are even more user features that can be enabled in real-time collaboration. The package contains an easy-to-install plugin to show the list of connected users and the sessions API to observe this collection.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--user-roles-and-permissions">

### User roles and permissions

CKEditor 5 supports setting user roles and permissions to enable/disable some editor functionalities for the user.

To learn how to define user roles and permissions, refer to the [Roles and permissions](#cs/latest/developer-resources/security/roles.html) guide of the Cloud Services documentation.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--users-presence-list">

### Users presence list

The [PresenceList](../../../api/module%5Freal-time-collaboration%5Fpresencelist-PresenceList.html) plugin provides a UI which displays all users that are currently connected to the edited document. The users are displayed as a row of avatars. The information about the users is provided by [CKEditor Cloud Services](#cs/latest/developer-resources/security/token-endpoint.html--user).

The presence list UI collapses to a dropdown if six or more users are connected.

By default, the local user avatar is always present on the list. You can hide it by setting the [displayMe](../../../api/module%5Freal-time-collaboration%5Fconfig-RtcPresenceListConfig.html#member-displayMe) configuration flag to `false`. It is also mark with an outline and listed first.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--installation-and-configuration">

#### Installation and configuration

The [plugin configuration](../../../api/module%5Freal-time-collaboration%5Fconfig-RtcPresenceListConfig.html) consists of three options:

* `container` – This is a DOM element that will hold the feature’s UI. It is required and already defined if you use the code from the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) tutorial.
* `collapseAt` – This optional parameter defines how many users need to be connected to switch the presence list to the dropdown view. The default value is `6`.
* `onClick` – Here, you can pass a callback function that will be invoked after a click in a presence list member. This function is invoked with two arguments: the `user` and the `element`. The first provides the clicked member details, and the second is the clicked element. This option is not required.

You can add the following code to the editor configuration object to get more control over the user presence list:

```
const editorConfig = {
    /* ... */

    presenceList: {
        // Existing configuration.
        container: document.querySelector('#editor-presence'),

        // Additional configuration.
        collapseAt: 3,
        onClick: ( user, element ) => console.log( user, element )
    },

    /* ... */
}

```

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--theme-customization">

#### Theme customization

Like in the whole CKEditor 5 Ecosystem [PostCSS](http://postcss.org) is used to handle styles with the power of [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables). The user presence list feature also uses it to make it possible to easily customize its appearance.

By default a presence list has two states with a dedicated design:

* Avatars displayed inline in the container (with fewer than 5 users).
* A dropdown panel for more than 5 users connected.

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--example-of-presence-list-customization-with-css-variables">

#### Example of presence list customization with CSS Variables

With [inheritance of CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables#Inheritance%5Fof%5FCSS%5FVariables) you can change the default values of variables. You can override these properties with a `.css` file or place your customizations directly into the `<head>` section of your page, but in this case, you will need to use a more specific CSS selector than `:root` (like `<body>`).

Add the following styles to the `style.css` file created in the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) guide:

```
/* Change the user presence list hue to greenish. */
.ck.ck-presence-list {
    --ck-user-avatar-background: #215a11;
}

.ck.ck-presence-list__balloon {
    /* Make a smaller user avatar in the dropdown list. */
    --ck-user-avatar-size: 25px;

    --ck-user-avatar-background: #215a11;
    --ck-color-presence-list-dropdown-background: #d0ecd2;
    --ck-color-presence-list-dropdown-arrow-border: #d0ecd2;
}

.ck.ck-presence-list__balloon .ck.ck-presence-list__dropdown-list-wrapper {
    /* Reduce the minimum and maximum width of the dropdown. */
    --ck-presence-list-dropdown-list-min-width: 100px;
    --ck-presence-list-dropdown-list-max-width: 150px;
}

```

To change the color assigned to users, refer to the [Users API](#ckeditor5/latest/features/collaboration/users.html--theme-customization) guide.

The examples above will generate the following presence list designs:

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--sessions">

### Sessions

The [Sessions](../../../api/module%5Freal-time-collaboration%5Frealtimecollaborativeediting%5Fsessions-Sessions.html) plugin stores information about users and sessions connected to the rich text editor. You may say that the presence list is a visualization of the sessions plugin data.

The difference between the sessions plugin and the [users plugin](#ckeditor5/latest/features/collaboration/users.html) is that the latter also keeps information about the users who are not currently connected to the editor (for example, a comment author who is currently offline).

If your integration uses the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html) and there are multiple channels used, the `Sessions` plugin aggregates users connected to all the channels.

There are two types of entries in the sessions plugin: connected users and sessions.

There is one session for each connection to a given channel. For example, for each open editor instance connecting to a given channel ID, there will be a session. Every session has a user. However, the same user can be linked with multiple sessions (for example, the same user opened the same URL in multiple tabs).

In other words, if the same user (with the same user ID) opens the same document in two different tabs, they will create two sessions but only one user will be connected. You will be able to see two selections in the same document, both in the same color, but only a single user in the [user presence list](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--users-presence-list).

<a id="ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--sessions-api">

#### Sessions API

If you use real-time collaboration features, the `Sessions` plugin will be loaded and available:

```
const sessionsPlugin = editor.plugins.get( 'Sessions' );

```

Check the [API of the Session plugin](../../../api/module%5Freal-time-collaboration%5Frealtimecollaborativeediting%5Fsessions-Sessions.html) to learn how to use it.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html">source file: "ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html"</a>

## Integrating revision history with your application

The revision history plugin [provides an API](../../../api/revision-history.html) that lets you create and manage named revisions of your document. To save and access revisions in your database, you first need to integrate this feature.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--integration-methods">

### Integration methods

This guide will discuss two ways to integrate CKEditor 5 with the revision history plugin:

* [A simple “load and save” integration](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--a-simple-load-and-save-integration) using the `RevisionHistory` plugin API.
* [An adapter integration](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--adapter-integration) which saves the revision data immediately in the database.

The adapter integration is the recommended approach for two reasons:

* It gives you better control over the data.
* It is more efficient and provides a better user experience, as the revisions’ data is loaded on demand rather than upfront before the editor is initialized.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--before-you-start">

### Before you start

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--preparing-a-custom-editor-setup">

#### Preparing a custom editor setup

To use the revision history plugin, you need to prepare a custom editor setup with the asynchronous version of the revision history feature included.

The easiest way to do that is by using the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). Pick a preset and start customizing your editor.

**In the “Features” section** of the Builder (2nd step), make sure to:

* enable the “Collaboration → Revision History” feature,
* turn off the “real-time” toggle next to the “Collaboration” group.

Once you finish the setup, the Builder will provide you with the necessary HTML, CSS, and JavaScript code snippets. We will use those code snippets in the next step.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--setting-up-a-sample-project">

#### Setting up a sample project

Once we have a custom editor setup we need a simple JavaScript project to run it. For this, we recommend cloning the basic project template from our repository:

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/sample-project sample-project
cd sample-project
npm install

```

Then, install the necessary dependencies:

```
npm install ckeditor5
npm install ckeditor5-premium-features

```

This project template uses [Vite](https://vitejs.dev/) under the hood and contains 3 source files that we will use: `index.html`, `style.css`, and `main.js`.

It is now the time to use our custom editor setup. **Go to the “Installation” section** of the Builder and copy the generated code snippets to those 3 files.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with a license key. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

After you have successfully obtained the license key open the `index.js` file and update the `your-license-key` string with your license key.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--building-the-project">

#### Building the project

Finally, build the project by running:

```
npm run dev

```

When you open the sample in the browser you should see the WYSIWYG editor with the revision history plugin. However, it still does not load or save any data. You will learn how to add data to the comments plugin later in this guide.

Let’s now dive deeper into the structure of this setup.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--basic-setups-anatomy">

#### Basic setup’s anatomy

Let’s now go through the key fragments of this basic setup.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--html-structure">

##### HTML structure

The HTML and CSS structure of the page creates two main containers:

* `<div class="editor-container__editor">` is the main container used by the editor.
* `<div class="revision-history">` is the main container used by revision history.
* `<div class="revision-history__editor">` is the container used by revision history that shows selected revision content.
* `<div class="revision-history__sidebar">` is the container used by revision history sidebar that holds revision list.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--javascript">

##### JavaScript

The `main.js` file sets up the editor instance:

* Adds the `revisionHistory` button to the editor toolbar.
* Loads all necessary editor plugins (including the [RevisionHistory](../../../api/module%5Frevision-history%5Frevisionhistory-RevisionHistory.html) plugin).
* Sets the `licenseKey` configuration option.
* Sets the `revisionHistory` configuration option to point to containers mentioned above.
* Defines the templates for the `RevisionHistoryIntegration` and `UsersIntegrations` plugins that we will use in the next steps of this tutorial.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--revision-history-api">

#### Revision history API

The integration below uses the revision history API. Making yourself familiar with the API may help you understand the code snippets. In case of any problems, refer to the [revision history API documentation](../../../api/revision-history.html).

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--next-steps">

#### Next steps

We have set up a simple JavaScript project that runs a basic CKEditor instance with the asynchronous version of the Revision history feature. It does not yet handle loading or saving data, though. The next two sections cover the two available integration methods.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--a-simple-load-and-save-integration">

### A simple “load and save” integration

In this solution, you load the user and revision data during the editor initialization. You save the revision data after you finish working with the editor (for example, when you submit the form containing the WYSIWYG editor).

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--loading-the-data">

#### Loading the data

After you include the revision history plugin in the editor, you need to create a plugin that will initialize users and existing revisions.

First, store the users and the revisions data into a variable that will be available for your plugin.

```
// Revisions data will be available under a global variable `revisions`.
const revisions = [
    {
        "id": "initial",
        "name": "Initial revision",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ………… by and between The Lower Shelf, the “Publisher”, and …………, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him/herself and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ………… by and between The Lower Shelf, the “Publisher”, and …………, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him/herself and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A."]}]'
            }
        },
        "createdAt": "2024-05-27T13:22:59.077Z",
        "attributes": {},
        "fromVersion": 1,
        "toVersion": 1
    },
    {
        "id": "e6f80e6be6ee6057fd5a449ab13fba25d",
        "name": "Updated with the actual data",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ",{"name":"revision-start","attributes":[["name","insertion:user-1:0"]],"children":[]},"1st",{"name":"revision-end","attributes":[["name","insertion:user-1:0"]],"children":[]}," ",{"name":"revision-start","attributes":[["name","insertion:user-1:1"]],"children":[]},"June 2020 ",{"name":"revision-end","attributes":[["name","insertion:user-1:1"]],"children":[]},"by and between The Lower Shelf, the “Publisher”, and ",{"name":"revision-start","attributes":[["name","insertion:user-1:2"]],"children":[]},"John Smith",{"name":"revision-end","attributes":[["name","insertion:user-1:2"]],"children":[]},", the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ",{"name":"revision-start","attributes":[["name","deletion:user-1:0"]],"children":[]},"…………",{"name":"revision-end","attributes":[["name","deletion:user-1:0"]],"children":[]}," by and between The Lower Shelf, the “Publisher”, and ",{"name":"revision-start","attributes":[["name","deletion:user-1:1"]],"children":[]},"…………",{"name":"revision-end","attributes":[["name","deletion:user-1:1"]],"children":[]},", the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him",{"name":"revision-start","attributes":[["name","deletion:user-1:2"]],"children":[]},"/herself",{"name":"revision-end","attributes":[["name","deletion:user-1:2"]],"children":[]}," and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature.",{"name":"revision-start","attributes":[["name","deletion:user-1:3"]],"children":[]}]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A.",{"name":"revision-end","attributes":[["name","deletion:user-1:3"]],"children":[]}]}]'
            }
        },
        "createdAt": "2024-05-27T13:23:52.553Z",
        "attributes": {},
        "fromVersion": 1,
        "toVersion": 20
    },
    {
        "id": "e6590c50ccbc86acacb7d27231ad32064",
        "name": "Inserted logo",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"figure","attributes":[["data-revision-start-before","insertion:user-1:0"],["class","image"]],"children":[{"name":"img","attributes":[["src","https://ckeditor.com/docs/ckeditor5/latest/assets/img/revision-history-demo.png"]],"children":[]}]},{"name":"h1","attributes":[],"children":[{"name":"revision-end","attributes":[["name","insertion:user-1:0"]],"children":[]},"PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[["data-revision-start-before","deletion:user-1:0"]],"children":[{"name":"revision-end","attributes":[["name","deletion:user-1:0"]],"children":[]},"PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]'
            }
        },
        "createdAt": "2024-05-27T13:26:39.252Z",
        "attributes": {},
        "fromVersion": 20,
        "toVersion": 24
    },
    // An empty current revision.
    {
        "id": "egh91t5jccbi894cacxx7dz7t36aj3k021",
        "name": null,
        "creatorId": null,
        "authorsIds": [],
        "diffData": {
            "main": {
                "insertions": '[{"name":"figure","attributes":[["class","image"]],"children":[{"name":"img","attributes":[["src","https://ckeditor.com/docs/ckeditor5/latest/assets/img/revision-history-demo.png"]],"children":[]}]},{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]'
            }
        },
        "createdAt": "2024-05-27T13:26:39.252Z",
        "attributes": {},
        "fromVersion": 24,
        "toVersion": 24
    }
];

```

Then, modify `RevisionHistoryIntegration` plugin to read the data from `revisions` array and load it to editor using `RevisionsRepository` API.

```
class RevisionHistoryIntegration extends Plugin {
    static get pluginName() {
        return 'RevisionHistoryIntegration';
    }

    static get requires() {
        return [ 'RevisionHistory' ];
    }

    init() {
        const revisionHistory = this.editor.plugins.get( 'RevisionHistory' );

        for ( const revisionData of revisions ) {
            revisionHistory.addRevisionData( revisionData );
        }
    }
}

```

Since revision data will be used, `editorConfig.root.initialData` is no longer needed and you can remove it as described in [Editor initial data and revision data](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--editor-initial-data-and-revision-data).

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--saving-the-data">

#### Saving the data

To save the revisions data, you need to get it from the `RevisionsRepository` plugin first. To do this, use the `getRevisions()` method.

Then, use the data to save it in your database in a selected way. See the example below. Remember to update your HTML structure to contain a button with the `get-data` ID, for example, `<button id="get-data">Get editor data</button>`.

```
ClassicEditor
    .create({
        ...editorConfig,
        attachTo: document.querySelector('#editor'),
    })
    .then( editor => {
        // After the editor is initialized, add an action to be performed after a button is clicked.
        document.querySelector( '#get-data' ).addEventListener( 'click', () => {
            const revisionHistory = editor.plugins.get( 'RevisionHistory' );

            // Get the document data and the revisions data (in JSON format, so it is easier to save).
            const editorData = editor.data.get();
            const revisionsData = revisionHistory.getRevisions( { toJSON: true } );

            // Now, use `editorData` and `revisionsData` to save the data in your application.
            //
            // Note: it is a good idea to verify the revision `creatorId` parameter when saving
            // a revision in the database. However, do not overwrite the value if it was set to `null`!
            console.log( editorData );
            console.log( revisionsData );
        } );
    } )
    .catch( error => console.error( error ) );

```

The integration is now ready to use with your rich text editor.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--demo">

#### Demo

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--console">

##### Console

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--revision-integration-console">

```

```

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--adapter-integration">

### Adapter integration

Adapter integration uses an adapter object – provided by you – to immediately save revisions data in your data store.

This is the recommended way of integrating revision history with your application as it lets you handle the client-server communication more securely. For example, you can check user permissions, validate sent data, or update the data with information obtained on the server side.

Additionally, revisions may include a significant amount of data. Loading multiple revisions of a big document may adversely impact the loading time of your application. When using an adapter, the revision data is loaded on demand, when needed. This improves the overall user experience.

It is important to load the revisions data during the plugin initialization step, that is, using the `init()` method of the integration plugin that you will provide (as in the example below).

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--saving-document-data-and-revisions-data">

#### Saving document data and revisions data

Before you move to the actual implementation remember that you should **always keep the document data and revisions data in sync**. This means that whenever you save one, you should save the other as well. This is natural for the “load & save” integration but for adapter integration, you need to keep that in mind. A mismatch in the data will result in the feature not working correctly.

Additionally, the document data should not be further post-processed after it is saved. To be precise, it should not be changed in a way that would result in a different model after you load the document data.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--implementation">

#### Implementation

First, define the adapter using the [RevisionHistory#adapter](../../../api/module%5Frevision-history%5Frevisionhistory-RevisionHistory.html#member-adapter) property. The adapter methods allow you to load and save changes in your database. Read the API reference for [RevisionHistoryAdapter](../../../api/module%5Frevision-history%5Frevisionhistoryadapter-RevisionHistoryAdapter.html) carefully to make sure that you integrate the feature with your application correctly.

Each change in revisions is performed immediately on the UI side. However, all adapter actions are asynchronous and are performed in the background. Because of this, all adapter methods need to return a `Promise`. When the promise is resolved, it means that everything went fine and a local change was successfully saved in the data store. When the promise is rejected, the editor throws a [CKEditorError](../../../api/module%5Futils%5Fckeditorerror-CKEditorError.html) error, which works nicely together with the [watchdog](#ckeditor5/latest/features/watchdog.html) feature. When you handle the server response, you can decide if the promise should be resolved or rejected.

While the adapter is saving the revision’s data, a pending action is automatically added to the editor [PendingActions](../../../api/module%5Fcore%5Fpendingactions-PendingActions.html) plugin. Thanks to this, you do not have to worry that the editor will be destroyed before the adapter action has finished.

Now you are ready to create the adapter. Let’s start with mocking revisions data. In real-life scenario this will be the data stored in your data storage.

```
// Revisions data will be available under a global variable `revisions`.
const revisions = [
    {
        "id": "initial",
        "name": "Initial revision",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ………… by and between The Lower Shelf, the “Publisher”, and …………, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him/herself and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ………… by and between The Lower Shelf, the “Publisher”, and …………, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him/herself and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A."]}]'
            }
        },
        "createdAt": "2024-05-27T13:22:59.077Z",
        "attributes": {},
        "fromVersion": 1,
        "toVersion": 1
    },
    {
        "id": "e6f80e6be6ee6057fd5a449ab13fba25d",
        "name": "Updated with the actual data",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ",{"name":"revision-start","attributes":[["name","insertion:user-1:0"]],"children":[]},"1st",{"name":"revision-end","attributes":[["name","insertion:user-1:0"]],"children":[]}," ",{"name":"revision-start","attributes":[["name","insertion:user-1:1"]],"children":[]},"June 2020 ",{"name":"revision-end","attributes":[["name","insertion:user-1:1"]],"children":[]},"by and between The Lower Shelf, the “Publisher”, and ",{"name":"revision-start","attributes":[["name","insertion:user-1:2"]],"children":[]},"John Smith",{"name":"revision-end","attributes":[["name","insertion:user-1:2"]],"children":[]},", the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of ",{"name":"revision-start","attributes":[["name","deletion:user-1:0"]],"children":[]},"…………",{"name":"revision-end","attributes":[["name","deletion:user-1:0"]],"children":[]}," by and between The Lower Shelf, the “Publisher”, and ",{"name":"revision-start","attributes":[["name","deletion:user-1:1"]],"children":[]},"…………",{"name":"revision-end","attributes":[["name","deletion:user-1:1"]],"children":[]},", the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him",{"name":"revision-start","attributes":[["name","deletion:user-1:2"]],"children":[]},"/herself",{"name":"revision-end","attributes":[["name","deletion:user-1:2"]],"children":[]}," and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature.",{"name":"revision-start","attributes":[["name","deletion:user-1:3"]],"children":[]}]},{"name":"p","attributes":[],"children":["Publishing formats are enumerated in Appendix A.",{"name":"revision-end","attributes":[["name","deletion:user-1:3"]],"children":[]}]}]'
            }
        },
        "createdAt": "2024-05-27T13:23:52.553Z",
        "attributes": {},
        "fromVersion": 1,
        "toVersion": 20
    },
    {
        "id": "e6590c50ccbc86acacb7d27231ad32064",
        "name": "Inserted logo",
        "creatorId": "user-1",
        "authorsIds": [ "user-1" ],
        "diffData": {
            "main": {
                "insertions": '[{"name":"figure","attributes":[["data-revision-start-before","insertion:user-1:0"],["class","image"]],"children":[{"name":"img","attributes":[["src","https://ckeditor.com/docs/ckeditor5/latest/assets/img/revision-history-demo.png"]],"children":[]}]},{"name":"h1","attributes":[],"children":[{"name":"revision-end","attributes":[["name","insertion:user-1:0"]],"children":[]},"PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[["data-revision-start-before","deletion:user-1:0"]],"children":[{"name":"revision-end","attributes":[["name","deletion:user-1:0"]],"children":[]},"PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]'
            }
        },
        "createdAt": "2024-05-27T13:26:39.252Z",
        "attributes": {},
        "fromVersion": 20,
        "toVersion": 24
    },
    // An empty current revision.
    {
        "id": "egh91t5jccbi894cacxx7dz7t36aj3k021",
        "name": null,
        "creatorId": null,
        "authorsIds": [],
        "diffData": {
            "main": {
                "insertions": '[{"name":"figure","attributes":[["class","image"]],"children":[{"name":"img","attributes":[["src","https://ckeditor.com/docs/ckeditor5/latest/assets/img/revision-history-demo.png"]],"children":[]}]},{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]',
                "deletions": '[{"name":"h1","attributes":[],"children":["PUBLISHING AGREEMENT"]},{"name":"h3","attributes":[],"children":["Introduction"]},{"name":"p","attributes":[],"children":["This publishing contract, the “contract”, is entered into as of 1st June 2020 by and between The Lower Shelf, the “Publisher”, and John Smith, the “Author”."]},{"name":"h3","attributes":[],"children":["Grant of Rights"]},{"name":"p","attributes":[],"children":["The Author grants the Publisher full right and title to the following, in perpetuity:"]},{"name":"ul","attributes":[],"children":[{"name":"li","attributes":[],"children":["To publish, sell, and profit from the listed works in all languages and formats in existence today and at any point in the future."]},{"name":"li","attributes":[],"children":["To create or devise modified, abridged, or derivative works based on the works listed."]},{"name":"li","attributes":[],"children":["To allow others to use the listed works at their discretion, without providing additional compensation to the Author."]}]},{"name":"p","attributes":[],"children":["These rights are granted by the Author on behalf of him and their successors, heirs, executors, and any other party who may attempt to lay claim to these rights at any point now or in the future."]},{"name":"p","attributes":[],"children":["Any rights not granted to the Publisher above remain with the Author."]},{"name":"p","attributes":[],"children":["The rights granted to the Publisher by the Author shall not be constrained by geographic territories and are considered global in nature."]}]'
            }
        },
        "createdAt": "2024-05-27T13:26:39.252Z",
        "attributes": {},
        "fromVersion": 24,
        "toVersion": 24
    }
];

```

Next, create adapter plugin based on `RevisionHistoryIntegration` plugin template to fetch revisions data asynchronously.

```
// A plugin that introduces the adapter.
class RevisionHistoryIntegration extends Plugin {
    static get pluginName() {
        return 'RevisionHistoryIntegration';
    }

    static get requires() {
        return [ 'RevisionHistory' ];
    }

    async init() {
        const revisionHistory = this.editor.plugins.get( 'RevisionHistory' );

        revisionHistory.adapter = {
            getRevision: ( { revisionId } ) => {
                return this._findRevision( revisionId );
            },
            updateRevisions: revisionsData => {
                const documentData = this.editor.getData();

                // This should be an asynchronous request to your database
                // that saves `revisionsData` and `documentData`.
                //
                // The document data should be saved each time a revision is saved.
                //
                // `revisionsData` is an array with objects,
                // where each object contains updated and new revisions.
                //
                // See the API reference for `RevisionHistoryAdapter` to learn
                // how to correctly integrate the feature with your application.
                //
                return Promise.resolve();
            }
        };

        // Add the revisions data for existing revisions.
        const revisionsData = await this._fetchRevisionsData();

        for ( const revisionData of revisionsData ) {
            revisionHistory.addRevisionData( revisionData );
        }
    }

    async _findRevision( revisionId ) {
        // Get the revision data based on its ID.
        // This should be an asynchronous request to your database.
        return Promise.resolve( revisions.find( revision => revision.id === revisionId ) );
    }

    async _fetchRevisionsData() {
        // Get a list of all revisions.
        // This should be an asynchronous call to your database.
        //
        // Note that the revision list should not contain the `diffData` property.
        // The `diffData` property may be big and will be fetched on demand by `adapter.getRevision()`.
        return Promise.resolve(revisions.map(revision => ({ ...revision, diffData: undefined })));
    }
}

```

Since revision data will be used, `editorConfig.root.initialData` is no longer needed and you can remove it as described in [Editor initial data and revision data](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--editor-initial-data-and-revision-data).

The adapter is now ready to use with your rich text editor.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--demo-2">

#### Demo

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--revision-history-adapter-actions-console">

##### Revision history adapter actions console

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--revision-adapter-console">

```

```

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--learn-more">

### Learn more

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--pending-actions">

#### Pending actions

Revision history uses the [pending actions](../../../api/module%5Fcore%5Fpendingactions-PendingActions.html) feature. Pending actions are added when the revisions data is being updated through the revision history adapter, to prevent closing the editor before the update finishes.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--editor-initial-data-and-revision-data">

#### Editor initial data and revision data

When the revision history feature is used, it is crucial to keep the revisions state in synchronization with the document data. Because of that, if there are any revisions saved for a document, the editor initial data will be discarded. The data saved with the most recent revision will be used instead.

If the editor’s initial data was set and it was different from the revision data, a warning will be logged in the console.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--autosave-integration">

#### Autosave integration

This section describes how to integrate revision history with the autosave plugin. This way, you can frequently save your document and revision data to keep them in sync.

The integration differs a bit whether you use the adapter or not.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--autosave-and-load-save-integration">

##### Autosave and “load & save” integration

Update the revision and make sure that the updated or created revision is saved together with the editor data:

```
autosave: {
    save: async editor => {
        const revisionTracker = editor.plugins.get( 'RevisionTracker' );

        await revisionTracker.update();

        const revisionData = revisionTracker.currentRevision.toJSON();
        const documentData = editor.getData();

        // `saveData()` should save the document and revision data in your database
        // and return a `Promise` that resolves when the save is completed.
        return saveData( documentData, revisionData );
    }
}

```

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--autosave-and-adapter-integration">

##### Autosave and adapter integration

Integration when using the adapter is easier. Your revision adapter should save the document data as well, as was already shown in the earlier examples.

Since the adapter already takes care of saving both revision data and the document data, all that needs to be done in the autosave integration is to update the revision:

```
autosave: {
    save: editor => {
        const revisionTracker = editor.plugins.get( 'RevisionTracker' );

        return revisionTracker.update();
    }
}

```

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--advanced-autosave-strategies">

##### Advanced autosave strategies

Presented integrations will keep on updating the same revision until the user explicitly saves or names the current revision, or closes the editor.

This may result in creating a big revision, containing a lot of changes. To prevent that, autosave integration could create new revisions based on your custom strategy.

For example, you may decide to save the current revision (unsaved changes) after a chosen number of autosave callbacks since the last saved revision:

```
// Create a new plugin that will handle the autosave logic.
class RevisionHistoryAutosaveIntegration extends Plugin {
    init() {
        this._saveAfter = 100; // Create a new revision after 100 saves.
        this._autosaveCount = 1; // Current autosave counter.
        this._lastCreatedAt = null; // Revision `createdAt` value, when the revision was last autosaved.
    }

    async autosave() {
        const revisionTracker = this.editor.plugins.get( 'RevisionTracker' );
        const currentRevision = revisionTracker.currentRevision;

        if ( currentRevision.createdAt > this._lastCreatedAt ) {
            // Revision was saved or updated in the meantime by a different source (not autosave).
            // Reset the counter.
            this._autosaveCount = 1;
        }

        if ( this._autosaveCount === this._saveAfter ) {
            // We reached the count. Save all changes as a new revision. Reset the counter.
            await revisionTracker.saveRevision();

            this._autosaveCount = 1;
            this._lastCreatedAt = currentRevision.createdAt;
        } else {
            // Try updating the "current revision" with the new document changes.
            // If there are any new changes, the `createdAt` property will change its value.
            // Do not raise the counter, if the revision has not been updated!
            await revisionTracker.update();

            if ( currentRevision.createdAt > this._lastCreatedAt ) {
                this._autosaveCount++;
                this._lastCreatedAt = currentRevision.createdAt;
            }
        }

        return true;
    }
}

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        extraPlugins: [
            // ...
            // Add the new plugin to the editor configuration:
            RevisionHistoryAutosaveIntegration
        ],
        // ...
        // Add the autosave configuration -- call the plugin method:
        autosave: {
            save: editor => {
                return editor.plugins.get( RevisionHistoryAutosaveIntegration ).autosave();
            }
        }
    } )
    .catch( error => console.error( error ) );

```

Similarly, you can implement a saving strategy that would include time since the last saved revision, number of operations, or multiple variables used together to decide if a new revision should be saved.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--how-revisions-are-updated-and-saved">

#### How revisions are updated and saved

Understanding how and when revisions are updated and saved is important when it comes to writing custom code that integrates with revision history, including autosave integration.

There are always at least two revisions available for a document: the initial revision and the current revision. If the document is new and no revisions have been created for it yet, the two revisions are created when the editor is initialized.

The **initial revision** contains the editor data from when the document was initialized for the first time. It can be empty or contain some content. The initial revision’s ID will equal to document ID or to `'initial'` if the document ID is not specified.

The **current revision** is a revision that stores all unsaved document changes, that is, changes that have not been saved in earlier revisions. It is always at the top of the revisions list. If a new revision is created, it will contain all unsaved changes and will be added below the current revision. Then, the current revision will be empty, until again updated with new, unsaved document changes. An empty current revision is not shown on the revisions list.

The current revision is not updated automatically when the document changes. The update can be done using the revisions feature API. It is enough to update the current revision when you need to save it, for example, in the autosave callback. The update is also triggered when the revision history view is opened. In this case, either the autosave callback is called, or the current revision is updated (if the autosave plugin is not used).

A new revision can be saved using the revisions feature API. Also, a new revision will be created when:

* A user saves a revision using the dropdown in the editor toolbar.
* A user gives a name to the current revision (in the revision history view).
* Each time the editor is initialized (a new current revision will be created, while the old current revision will become a regular revision).

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--save-or-update-revision-using-the-feature-api">

##### Save or update revision using the feature API

```
const revisionTrackerPlugin = this.editor.plugins.get( 'RevisionTracker' );

// Updates the "current revision", that is, the revision containing unsaved changes.
revisionTrackerPlugin.update();

// Creates a new revision that will contain all the unsaved changes.
// See the API reference to learn more.
revisionTrackerPlugin.saveRevision();
revisionTrackerPlugin.saveRevision( { name: 'My revision' } );

```

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html--revision-history-samples">

### Revision history samples

Please visit the [ckeditor5-collaboration-samples](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master) GitHub repository to find several sample integrations of the revision history feature.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history.html">source file: "ckeditor5/latest/features/collaboration/revision-history/revision-history.html"</a>

## Revision history overview

The revision history feature is a document versioning tool that shows you how your content has changed over time. It lets you review both content changes and suggestions made with the track changes feature.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history.html--demo">

### Demo

Use the editor below to test document versioning. Introduce changes, then use the revision history toolbar button  to gain access to the revision tools.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history.html--additional-feature-information">

### Additional feature information

With the revision history feature, you can:

* Create a named historical version – a revision – of the content by bundling changes together in a save cycle.
* View the chronological history of revisions of your content.
* Restore an earlier revision of your document to reverse any changes.
* Compare selected revisions to each other and view changes between.

You can also read a dedicated blog post that [compares revision history with the track changes feature](https://ckeditor.com/blog/ckeditor-5-comparing-revision-history-with-track-changes/) and points out similarities and differences between these two features.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history.html--use-as-a-standalone-plugin">

### Use as a standalone plugin

Revision history does not require real-time collaboration to work. You can add it to CKEditor 5 just like any other plugin.

To learn how to integrate revision history as a standalone plugin, refer to the [Integrating revision history with your application](#ckeditor5/latest/features/collaboration/revision-history/revision-history-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/revision-history/revision-history.html--use-with-real-time-collaboration">

### Use with real-time collaboration

If you are using the real-time collaboration feature, refer to the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html"</a>

## Integrating track changes with custom features

The track changes feature was designed with custom features in mind. In this guide, you will learn how to integrate your plugins with the track changes feature.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--enabling-commands">

### Enabling commands

CKEditor 5 uses [commands](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) to change the editor content. Most modifications of the editor content are done through command execution. Also, commands are usually connected with toolbar buttons that represent their state. For example, if a given command is disabled at the moment, the toolbar button is disabled as well.

By default, a command is disabled when tracking changes is turned on. This is to prevent errors and incorrect behavior of a command that has not been prepared to work in the suggestion mode. The first step to integrating your command is to enable it:

```
const trackChangesEditing = editor.plugins.get( 'TrackChangesEditing' );

trackChangesEditing.enableCommand( 'commandName' );

```

Now the command will be enabled in the track changes mode. However, this on its own does not introduce any additional functionality related to integration with the track changes feature. The command will work as though track changes is turned off.

If your command does not introduce any change to the document model (for example, it shows a UI component), it may be enough to just simply enable it.

Further integration steps will depend on what kind of change your command performs.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--insertions-and-deletions">

### Insertions and deletions

Many custom features are focused on introducing a new kind of element or a widget. It is recommended to use [model.insertContent()](../../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) to insert such object into the document content. This method, apart from taking care of maintaining a proper document structure, is also integrated with the track changes feature. Any content inserted with this method will be automatically marked with an insertion suggestion.

Similarly, removing is also integrated with track changes through the integration with [model.deleteContent()](../../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-deleteContent). Calling this method while in the suggestion mode will create a deletion suggestion instead. The same goes for actions that remove content, for example using the Backspace and Delete keys, typing over selected content, or pasting over the selected content.

In summary, if your command inserts or removes a widget, chances are it will work in the suggestion mode out-of-the-box.

One thing that may still need your attention is suggestion description. To generate a proper suggestion description, you need to [register a label for the introduced element](../../../api/module%5Ftrack-changes%5Fsuggestiondescriptionfactory-SuggestionDescriptionFactory.html#function-registerElementLabel). The description mechanism supports translations and different labels for single and multiple added/removed elements.

An example of integration for the page break element:

```
const t = editor.t;

trackChangesEditing.descriptionFactory.registerElementLabel(
    'pageBreak',

    quantity => t( {
        string: 'page break',
        plural: '%0 page breaks',
        id: 'ELEMENT_PAGE_BREAK'
    }, quantity )
);

```

After registering an element label, it will be used in suggestion descriptions. For the above example, the description may be “**Remove:** page break” or, for example, “**Insert:** 3 page breaks.” Using the translation system and adding translations for custom features is described in the [Localization](#ckeditor5/latest/framework/deep-dive/ui/localization.html) guide.

If you do not need to support multiple languages, you can skip using translations system:

```
trackChangesEditing.descriptionFactory.registerElementLabel(
    'customElement',

    quantity => quantity == 1 ? 'custom element' : quantity + ' custom elements'
);

```

If you do not specify a label, then the model element is used by default.

If for some reason your feature cannot use `model.insertContent()` and `model.deleteContent()`, or you need a more advanced integration, you can assign a custom callback that will be called whenever the command is executed while suggestion mode is on:

```
trackChangesEditing.enableCommand( 'commandName', ( executeCommand, options ) => {
    // Here you can overwrite what happens when the command is executed in the suggestion mode.
    // See the API documentation to learn more about the parameters passed to the callback.
    // ...
} );

```

Then you will need to use one of the following methods from the track changes API:

* [markInsertion()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markInsertion) – Creates an insertion suggestion on a given range.
* [markMultiRangeInsertion()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markMultiRangeInsertion) – Creates one insertion suggestion that contains multiple ranges.
* [markDeletion()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markDeletion) – Creates a deletion suggestion on a given range.
* [markMultiRangeDeletion()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markMultiRangeDeletion) – Creates one deletion suggestion that contains multiple ranges.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--attribute-changes">

### Attribute changes

Another category of changes is attribute changes. If your custom feature introduces attribute that is applied to text or can be changed by the user, you may want to implement this type of integration.

To enable tracking attribute changes, use [enableDefaultAttributesIntegration()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-enableDefaultAttributesIntegration) method. It is a simple helper, designed to handle most of the scenarios related to attribute changes. It will enable the command, so you do not need to additionally use `enableCommand()`.

Additionally, you will need to register every attribute key that you will want to track. This is done using [SuggestionsConversion#registerInlineAttribute()](../../../api/module%5Fcollaboration-core%5Fsuggestions%5Fsuggestionsconversion-SuggestionsConversion.html#function-registerInlineAttribute) and [SuggestionsConversion#registerBlockAttribute()](../../../api/module%5Fcollaboration-core%5Fsuggestions%5Fsuggestionsconversion-SuggestionsConversion.html#function-registerBlockAttribute) methods.

For example, if you have a `customCommand` that changes the value of `customAttribute` set on text, use the following snippet:

```
trackChangesEditing.enableDefaultAttributesIntegration( 'customCommand' );

const suggestionsConversion = editor.plugins.get( 'SuggestionsConversion' );
suggestionsConversion.registerInlineAttribute( 'customAttribute' );

```

Attributes are categorized into two groups: inline (for attributes set on text) and block (for attributes set on model elements). This differentiation is necessary due to the distinct logic for handling suggestions made on different types of content.

Each command integrated this way will track all registered attributes and create suggestions for their changes. Each attribute should be registered only once.

For attribute formatting each attribute registered in track changes should also have its label registered:

```
const t = editor.t;

plugin.descriptionFactory.registerAttributeLabel( 'bold', t( 'bold' ) );

```

If you require more complex logic when evaluating the suggestion description, refer to [Setting custom suggestion description](#ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--setting-custom-suggestion-description) section below.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--tracking-attribute-changes-in-custom-code">

#### Tracking attribute changes in custom code

In case if some of your custom code makes changes on attributes outside of command execution, you can use the [recordAttributeChanges()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-recordAttributeChanges) method. This method allows you to wrap any code that modifies attributes in a callback, and the track changes plugin will automatically create suggestions for all attribute changes that occur during the callback execution.

Here’s an example of using `recordAttributeChanges()` with a custom callback:

```
const trackChangesEditing = editor.plugins.get( 'TrackChangesEditing' );

// Use `recordAttributeChanges` to track changes in your custom code.
trackChangesEditing.recordAttributeChanges( () => {
    editor.model.change( writer => {
        const currentSelectionRange = editor.model.document.selection.getFirstRange();

        // Set bold attribute on the current selection.
        writer.setAttribute( 'bold', true, currentSelectionRange );
    } );
} );

```

Remember that for the changes to be tracked, the attributes must be registered using either `registerInlineAttribute()` or `registerBlockAttribute()`.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--other-formatting-changes">

### Other formatting changes

The above sections cover typical custom plugins and commands, which simply add a new element or change some attributes.

If your feature is more complex, for example, it introduces multiple attributes which values depend on each other, or you command performs multiple related changes at once, then you may need to use a different approach.

In such cases, you will need to pass a custom callback to [enableCommand()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-enableCommand) which will overwrite the default command behavior when track changes is on. In the callback you will need to use the track changes API:

* [markInlineFormat()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markInlineFormat) – Marks a given range as an inline format suggestion. Used for attribute changes on inline elements and text.
* [markBlockFormat()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markBlockFormat) – Marks a format suggestion on a block element.
* [markMultiRangeBlockFormat()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markMultiRangeBlockFormat) – Used for format suggestions that contain multiple elements that are not next to one another.

Refer to the API documentation of these methods to learn more.

Format suggestions are strictly connected with commands. These suggestions data consists of: the range on which command was fired, the command name and the command options. When the suggestion is accepted, the specified command is executed on the suggestion range with the specified options. In other words, the original command execution is “replayed”.

The general approach to handle format suggestions for your custom feature is to use a similar logic as in your custom feature but instead of applying changes to the content, create a suggestion using the track changes API:

1. Overwrite the command callback (using `enableCommand()`) so the command is not executed.
2. Use the same logic as in your custom command to decide whether the command should do anything.
3. Use the same logic as in your custom command to evaluate all command parameters that has not been set (and would use a default value if the command’s original code was executed). This is important: a suggestion must have all parameters set, so its execution does not rely on the current content state but on the content state at the time when the suggestion was created.
4. Use the selection range or evaluate a more precise range(s) for the suggestion(s).
5. Use [markInlineFormat()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markInlineFormat) or [markBlockFormat()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-markBlockFormat) to create one or more suggestions using the previously evaluated variables.

Note, that if the command is integrated this way, the command change will not be actually executed (in other words, the action will not be reflected in the content). The command will be executed only after the suggestion is eventually accepted.

An example of an integration for `imageTypeInline` command:

```
plugin.enableCommand( 'imageTypeInline', ( executeCommand, options ) => {
    // Commands work on the current selection, so the track
    // changes integration also works on the current selection.
    // Find element that will be affected.
    const image = imageUtils.getClosestSelectedImageElement( editor.model.document.selection );

    editor.model.change( () => {
        plugin.markBlockFormat(
            image,
            {
                // The command to be executed when the suggestion is accepted.
                commandName: 'imageTypeInline',
                // Parameters for the command.
                commandParams: [ options ]
            },
            [],
            'convertBlockImageToInline' );
    } );
} );

```

See next section to learn how to generate labels for formatting suggestions.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html--setting-custom-suggestion-description">

### Setting custom suggestion description

To complete the integration of your command using the format suggestion or for more complex logic for attribute suggestion, you will need to [provide a callback that will generate a description for such a suggestion](../../../api/module%5Ftrack-changes%5Fsuggestiondescriptionfactory-SuggestionDescriptionFactory.html#function-registerDescriptionCallback). This is different from registering a label for insertion/deletion suggestions as format suggestions are more varied and complex.

An example of a description callback for the block quote command:

```
plugin.descriptionFactory.registerDescriptionCallback( suggestion => {
    const { data } = suggestion;

    if ( !data || data.commandName != 'blockQuote' ) {
        return;
    }

    if ( data.commandParams[ 0 ].forceValue ) {
        return {
            type: 'format',
            content: '*Set format:* block quote'
        };
    }

    return {
        type: 'format',
        content: '*Remove format:* block quote'
    };
} );

```

Note that the description callback can be also used for insertion and deletion suggestions if you want to overwrite the default description.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html"</a>

## Saving data without suggestions

Sometimes you may need to save editor data with all the suggestions accepted or discarded. Common cases include document preview or printing.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html--track-changes-data-plugin">

### Track changes data plugin

To enable saving data without suggestions you will need to use the `TrackChangesData` plugin. It is available in the track changes package. Import it and add to your setup:

Then you can use the [track changes data plugin API](../../../api/module%5Ftrack-changes%5Ftrackchangesdata-TrackChangesData.html) to get the editor data with all the suggestions accepted or discarded:

```
const data = await editor.plugins.get( 'TrackChangesData' ).getDataWithAcceptedSuggestions();

```

Note that this method is asynchronous (it returns a promise that resolves with the editor data).

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html--configuring-track-changes-data-plugin">

### Configuring track changes data plugin

In most common cases, there is no need for any configuration regarding the track changes data plugin. However, sometimes running the track changes data plugin needs more effort.

In general, the track changes data plugin uses a temporary editor instance to load the current data, accept or discard the suggestions and then get the editor data.

This may raise some issues in the following scenarios:

* if some actions are performed after the editor is initialized (for example, loading some kind of data for your custom plugins),
* if you use your own, custom editor class, whose API is different from `ClassicEditor`.

In these cases, you can provide your own callback as a configuration parameter for the track changes data plugin:

```
{
    trackChangesData: {
        editorCreator: ( config, createElement ) => {
            // Custom callback.
            // ...
        }
    }
}

```

Two parameters are passed to the callback:

* `config` \- The editor configuration that should be used to initialize the editor.
* `createElement` \- A function that creates a DOM element, should you need one (or more) to initialize your editor. The DOM elements created by this function are hidden and will be cleared after the plugin finishes its work.

The callback should return a promise that resolves with the editor instance.

An example of a callback using a multi-root editor that requires passing multiple roots in the config parameter of the `.create()` method.

```
{
    trackChangesData: {
        editorCreator: ( config, createElement ) => {
            return CustomMultiRootEditor.create( {
                ...config,
                roots: {
                    // ... other config
                    header: {
                        element: createElement(),
                    },
                    content: {
                        element: createElement(),
                    },
                    footer: {
                        element: createElement(),
                    }
                }
            } );
        }
    }
}

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html"</a>

## Increasing suggestions granularity

To maintain a low number of suggestions in the document, in some cases, the track changes feature automatically joins suggestions added by the same user. This happens when, for example, two insertion suggestions are made next to each other, or two formatting suggestions are made on the same text. This leads to a less cluttered UI, and as a result generally provides a better user experience.

However, in some specific cases, you may require to have more control over how and when suggestions are joined, and you might want to prevent this automatic mechanism. For this, you can use [config.trackChanges.mergeNestedSuggestions](../../../api/module%5Ftrack-changes%5Ftrackchangesconfig-TrackChangesConfig.html#member-mergeNestedSuggestions) configuration option and [the tracking sessions](#ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--tracking-sessions) mechanism.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--auto-merging-nested-suggestions">

### Auto-merging nested suggestions

By default, suggestions **on** an object (such as image or table) will be automatically merged with suggestions **inside** the object (for example, a change in image caption, or a table cell). For example, creating a table and writing some text inside the table will result in one suggestion.

This behavior can be changed by setting the [config.trackChanges.mergeNestedSuggestions](../../../api/module%5Ftrack-changes%5Ftrackchangesconfig-TrackChangesConfig.html#member-mergeNestedSuggestions) configuration option to `false`. In the scenario above, there would be two separate suggestions: one for the inserted table and one for the inserted text.

```
{
    trackChanges: {
        mergeNestedSuggestions: false
    }
    // Other configuration
}

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--tracking-sessions">

### Tracking sessions

To stop track changes from automatically joining suggestions made by the same user, [start a new tracking session](#ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--starting-a-new-tracking-session). Suggestions created in the new tracking session will not be joined with suggestions created in any of the previous tracking session.

From the technical point of view, after starting a new tracking session, newly created suggestions will have a unique `trackingSessionId` [attribute](../../../api/module%5Ftrack-changes%5Fsuggestion-Suggestion.html#member-attributes). This will prevent them from being joined to already existing suggestions.

If you are using a asynchronous integration, make sure that you correctly save and load suggestion `attributes` together with the rest of the suggestion data.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--starting-a-new-tracking-session">

#### Starting a new tracking session

To start a new tracking session, call the [TrackChangesEditing#startTrackingSession()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-startTrackingSession) method. From now on, all newly created suggestions will have a unique `trackingSessionId` attribute set. That ID value is returned by the method.

```
editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession();

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--resuming-previous-session">

#### Resuming previous session

You can also resume one of the previous tracking sessions by calling [TrackChangesEditing#startTrackingSession()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-startTrackingSession) and passing a previously set `trackingSessionId` as the `id` parameter.

```
editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession( 'somePreviousId' );

```

To “resume” tracking session for suggestions that were added before introducing [TrackChangesEditing#startTrackingSession()](../../../api/module%5Ftrack-changes%5Ftrackchangesediting-TrackChangesEditing.html#function-startTrackingSession) you may pass `null` as the `id` parameter. It will also stop adding the `trackingSessionId` attribute to new suggestions.

```
editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession( null );

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--demo">

### Demo

1. Add some text with track changes enabled. You may add more text next to created suggestions to see how the suggestions are automatically expanded.
2. Press the “Start new tracking session” button above the editor, and continue typing after one of the previously created suggestions.
3. See how new suggestion is created instead of expanding the existing suggestion.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-granular-suggestions.html--starting-a-new-session-on-editor-initialization">

### Starting a new session on editor initialization

One of the primary use cases is to start a new tracking session whenever the user opens the editor and/or after some time has passed.

Below you will find an example where a new tracking session is started whenever editor is created.

```
ClassicEditor
    .create( {
        // ... Editor configuration ...
    } )
    .then( editor => {
        // You can store the id if you need it later to resume previous tracking session.
        const trackingSessionId = editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession();
    } )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html"</a>

## Integrating track changes with your application

The track changes plugin provides an API that lets you manage suggestions added to the document. To save and access suggestions in your database, you first need to integrate this feature.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--integration-methods">

### Integration methods

This guide will discuss two ways to integrate CKEditor 5 with your suggestions data source:

* [A simple “load and save” integration](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--a-simple-load-and-save-integration) using the `TrackChanges` plugin API.
* [An adapter integration](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--adapter-integration) which saves the suggestions data immediately in the database.

The adapter integration is the recommended one because it gives you better control over the data.

It is also recommended to use the track changes plugin together with the comments plugin. [Check how to integrate the comments plugin](#ckeditor5/latest/features/collaboration/comments/comments-integration.html) with your WYSIWYG editor.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--before-you-start">

### Before you start

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--preparing-a-custom-editor-setup">

#### Preparing a custom editor setup

To use the track changes plugin, prepare a custom editor setup with the asynchronous version of the track changes feature included.

The easiest way to do that is by using the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). Pick a preset and start customizing your editor.

**In the “Features” section** of the Builder (2nd step), make sure to:

* turn off the “real-time” toggle next to the “Collaboration” group,
* enable the “Collaboration → Track Changes” feature.

Once you finish the setup, the Builder will provide you with the necessary HTML, CSS, and JavaScript code snippets. We will use those code snippets in the next step.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--setting-up-a-sample-project">

#### Setting up a sample project

Once we have a custom editor setup we need a simple JavaScript project to run it. For this, we recommend cloning the basic project template from our repository:

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/sample-project sample-project
cd sample-project
npm install

```

Then, install the necessary dependencies:

```
npm install ckeditor5
npm install ckeditor5-premium-features

```

This project template uses [Vite](https://vitejs.dev/) under the hood and contains 3 source files that we will use: `index.html`, `style.css`, and `main.js`.

It is now the time to use our custom editor setup. **Go to the “Installation” section** of the Builder and copy the generated code snippets to those 3 files.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with a license key. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

After you have successfully obtained the license key open the `main.js` file and update the `your-license-key` string with your license key.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--building-the-project">

#### Building the project

Finally, build the project by running:

```
npm run dev

```

When you open the sample in the browser you should see the WYSIWYG editor with the track changes plugin. However, it still does not load or save any data. You will learn how to add data to the track changes plugin later in this guide.

Let’s now dive deeper into the structure of this setup.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--basic-setups-anatomy">

#### Basic setup’s anatomy

Let’s now go through the key fragments of this basic setup.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--html-structure">

##### HTML structure

The HTML and CSS structure of the page creates two columns:

* `<div class="editor-container__editor">` is the container used by the editor.
* `<div class="editor-container__sidebar">` is the container used by the sidebar that holds the annotations (namely track changes).

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--javascript">

##### JavaScript

The `main.js` file sets up the editor instance:

* Loads all necessary editor plugins (including the [TrackChanges](../../../api/module%5Ftrack-changes%5Ftrackchanges-TrackChanges.html) plugin).
* Sets the `licenseKey` configuration option.
* Sets the `sidebar.container` configuration option to the container mentioned above.
* Adds the `trackChanges` button to the editor toolbar.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--comments">

#### Comments

Track changes use the [comments plugin](#ckeditor5/latest/features/collaboration/comments/comments.html) to allow discussion in suggestions. You should be familiar with the [comments integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html) guide before you start integrating suggestions.

For that reason, the `main.js` file [obtained in the previous step](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--javascript) does the following on top of the track changes plugin setup:

* Loads the [Comments](../../../api/module%5Fcomments%5Fcomments-Comments.html) plugin (dependency of the `TrackChanges` plugin).
* Defines the plugin templates:  
  * For the `CommentsIntegration` plugin (learn how to [save comments](#ckeditor5/latest/features/collaboration/comments/comments-integration.html)).
  * For the `UsersIntegrations` plugin that is shared by both track changes and comments features and we will be used in the next steps of this tutorial.
* Adds the `comment` and `commentsArchive` buttons to the editor toolbar.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--next-steps">

#### Next steps

We have set up a simple JavaScript project that runs a basic CKEditor instance with the asynchronous version of the track changes feature. It does not yet handle loading or saving data, though. The next two sections cover the two available integration methods.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--a-simple-load-and-save-integration">

### A simple “load and save” integration

In this solution, user and suggestions data is loaded during the editor initialization, and suggestions data is saved after you finish working with the editor (for example, when you submit the form containing the WYSIWYG editor).

This method is recommended only if you can trust your users or if you provide additional validation of the submitted data to make sure that the user changed their suggestions only.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--loading-the-data">

#### Loading the data

When the track changes plugin is already included in the editor, you need to create plugins which will initialize users and existing suggestions.

First, dump the users and the suggestions data to a variable that will be available for your plugin.

```
// Application data will be available under a global variable `appData`.
const appData = {
    // Users data.
    users: [
        {
            id: 'user-1',
            name: 'Mex Haddox'
        },
        {
            id: 'user-2',
            name: 'Zee Croce'
        }
    ],

    // The ID of the current user.
    userId: 'user-1',

    // Comment threads data.
    commentThreads: [
        {
            threadId: 'thread-1',
            comments: [
                {
                    commentId: 'comment-1',
                    authorId: 'user-1',
                    content: '<p>Are we sure we want to use a made-up disorder name?</p>',
                    createdAt: new Date( '09/20/2018 14:21:53' ),
                    attributes: {}
                },
                {
                    commentId: 'comment-2',
                    authorId: 'user-2',
                    content: '<p>Why not?</p>',
                    createdAt: new Date( '09/21/2018 08:17:01' ),
                    attributes: {}
                }
            ],
            context: {
                type: 'text',
                value: 'Bilingual Personality Disorder'
            },
            unlinkedAt: null,
            resolvedAt: null,
            resolvedBy: null,
            attributes: {}
        }
    ],

    // Suggestions data.
    suggestions: [
        {
            id: 'suggestion-1',
            type: 'insertion',
            authorId: 'user-2',
            createdAt: new Date( 2019, 1, 13, 11, 20, 48 ),
            data: null,
            attributes: {}
        },
        {
            id: 'suggestion-2',
            type: 'deletion',
            authorId: 'user-1',
            createdAt: new Date( 2019, 1, 14, 12, 7, 20 ),
            data: null,
            attributes: {}
        },
        {
            id: 'suggestion-3',
            type: 'attribute:bold|ci1tcnk0lkep',
            authorId: 'user-1',
            createdAt: new Date( 2019, 2, 8, 10, 2, 7 ),
            data: {
                key: 'bold',
                oldValue: null,
                newValue: true
            },
            attributes: {
                groupId: 'e29adbb2f3963e522da4d2be03bc5345f'
            }
        }
    ],

    // Editor initial data.
    initialData:
        `<h2>
            <comment-start name="thread-1"></comment-start>
            Bilingual Personality Disorder
            <comment-end name="thread-1"></comment-end>
        </h2>
        <p>
            This may be the first time you hear about this
            <suggestion-start name="insertion:suggestion-1:user-2"></suggestion-start>
            made-up<suggestion-end name="insertion:suggestion-1:user-2"></suggestion-end>
            disorder but it actually is not that far from the truth.
            As recent studies show, the language you speak has more effects on you than you realize.
            According to the studies, the language a person speaks affects their cognition,
            <suggestion-start name="deletion:suggestion-2:user-1"></suggestion-start>
            feelings, <suggestion-end name="deletion:suggestion-2:user-1"></suggestion-end>
            behavior, emotions and hence <strong>their personality</strong>.
        </p>
        <p>
            This shouldn’t come as a surprise
            <a href="https://en.wikipedia.org/wiki/Lateralization_of_brain_function">since we already know</a>
            that different regions of the brain become more active depending on the activity.
            The structure, information and especially
            <suggestion-start name="attribute:bold|ci1tcnk0lkep:suggestion-3:user-1"></suggestion-start><strong>the
            culture of languages<suggestion-end name="attribute:bold|ci1tcnk0lkep:suggestion-3:user-1"></strong></suggestion-end>
            varies substantially
            and the language a person speaks is an essential element of daily life.
        </p>`
};

```

The Builder’s output sample already provides templates of three plugins: `UsersIntegration`, `CommentsIntegration`, and `TrackChangesIntegration`. Replace them with ones that read the data from `appData` and use the [Users](../../../api/module%5Fcollaboration-core%5Fusers-Users.html), [CommentsRepository](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html), and [TrackChanges](../../../api/track-changes.html) APIs, respectively:

```
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Users' ];
    }

    static get pluginName() {
        return 'UsersIntegration';
    }

    init() {
        const usersPlugin = this.editor.plugins.get( 'Users' );

        // Load the users data.
        for ( const user of appData.users ) {
            usersPlugin.addUser( user );
        }

        // Set the current user.
        usersPlugin.defineMe( appData.userId );
    }
}

class CommentsIntegration extends Plugin {
    static get requires() {
        return [ 'CommentsRepository', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'CommentsIntegration';
    }

    init() {
        const commentsRepositoryPlugin = this.editor.plugins.get( 'CommentsRepository' );

        // Load the comment threads data.
        for ( const commentThread of appData.commentThreads ) {
            commentsRepositoryPlugin.addCommentThread( commentThread );
        }
    }
}

class TrackChangesIntegration extends Plugin {
    static get requires() {
        return [ 'TrackChanges', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'TrackChangesIntegration';
    }

    init() {
        const trackChangesPlugin = this.editor.plugins.get( 'TrackChanges' );

        // Load the suggestions data.
        for ( const suggestion of appData.suggestions ) {
            trackChangesPlugin.addSuggestion( suggestion );
        }
    }
}

```

Update the `editorConfig.root.initialData` property to use `appData.initialData` value:

```
const editorConfig = {
    // ...

    root: {
        initialData: appData.initialData
    },

    // ...
};

```

And build the project:

```
npm run dev

```

You should now we see an editor instance with one comment thread and several track changes suggestions.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--saving-the-data">

#### Saving the data

To save the suggestions data you need to get it from the `TrackChanges` API first. To do this, use the [getSuggestions()](../../../api/module%5Ftrack-changes%5Ftrackchanges-TrackChanges.html#function-getSuggestions) method.

Then, use the suggestions data to save it in your database in the way you prefer. See the example below.

In `index.html` add:

```
<button id="get-data">Get data</button>

```

In `main.js` update the `ClassicEditor.create()` call with a chained `then()`:

```
ClassicEditor
    .create( /* ... */ )
    .then( editor => {
        // After the editor is initialized, add an action to be performed after a button is clicked.
        const trackChanges = editor.plugins.get( 'TrackChanges' );

        // Get the data on demand.
        document.querySelector( '#get-data' ).addEventListener( 'click', () => {
            const editorData = editor.data.get();
            const suggestionsData = trackChanges.getSuggestions( {
                skipNotAttached: true,
                toJSON: true
            } );

            // Now, use `editorData` and `suggestionsData` to save the data in your application.
            // For example, you can set them as values of hidden input fields.
            console.log( editorData );
            console.log( suggestionsData );
        } );
    } )
    .catch( error => console.error( error ) );

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--demo">

#### Demo

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--tc-integration-console">

```

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--adapter-integration">

### Adapter integration

Adapter integration uses an adapter object – provided by you – to immediately save suggestions in your data store. This is the recommended way of integrating track changes with your application because it lets you handle client-server communication more securely. For example, you can check user permissions, validate sent data, or update the data with information obtained on the server side, like the suggestion creation date. You will see how to handle the server response in the following steps.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--implementation">

#### Implementation

First, define the adapter using the [TrackChanges#adapter](../../../api/module%5Ftrack-changes%5Ftrackchanges-TrackChanges.html#member-adapter) setter. [Adapter methods](../../../api/module%5Ftrack-changes%5Ftrackchanges-TrackChangesAdapter.html) allow you to load and save changes in your database.

On the UI side each change in suggestions is performed immediately, however, all adapter actions are asynchronous and are performed in the background. Because of this all adapter methods need to return a `Promise`. When the promise is resolved, it means that everything went fine and a local change was successfully saved in the data store. When the promise is rejected, the editor throws a [CKEditorError](../../../api/module%5Futils%5Fckeditorerror-CKEditorError.html) error, which works nicely together with the [watchdog](#ckeditor5/latest/features/watchdog.html) feature. When you handle the server response you can decide if the promise should be resolved or rejected.

While the adapter is saving the suggestion data, a pending action is automatically added to the editor [PendingActions](../../../api/module%5Fcore%5Fpendingactions-PendingActions.html) plugin, so you do not have to worry that the editor will be destroyed before the adapter action has finished.

Now you are ready to implement the adapter.

If you have set up the sample project as [recommended in the “Before you start” section](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--before-you-start), open the `main.js` file and add the following code right after the imports:

```
// Application data will be available under a global variable `appData`.
const appData = {
    // Users data.
    users: [
        {
            id: 'user-1',
            name: 'Mex Haddox'
        },
        {
            id: 'user-2',
            name: 'Zee Croce'
        }
    ],

    // The ID of the current user.
    userId: 'user-1',

    // Comment threads data.
    commentThreads: [
        {
            threadId: 'thread-1',
            comments: [
                {
                    commentId: 'comment-1',
                    authorId: 'user-1',
                    content: '<p>Are we sure we want to use a made-up disorder name?</p>',
                    createdAt: new Date( '09/20/2018 14:21:53' ),
                    attributes: {}
                },
                {
                    commentId: 'comment-2',
                    authorId: 'user-2',
                    content: '<p>Why not?</p>',
                    createdAt: new Date( '09/21/2018 08:17:01' ),
                    attributes: {}
                }
            ],
            context: {
                type: 'text',
                value: 'Bilingual Personality Disorder'
            },
            unlinkedAt: null,
            resolvedAt: null,
            resolvedBy: null,
            attributes: {}
        }
    ],

    // Editor initial data.
    initialData:
        `<h2>
            <comment-start name="thread-1"></comment-start>
            Bilingual Personality Disorder
            <comment-end name="thread-1"></comment-end>
        </h2>
        <p>
            This may be the first time you hear about this
            <suggestion-start name="insertion:suggestion-1:user-2"></suggestion-start>
            made-up<suggestion-end name="insertion:suggestion-1:user-2"></suggestion-end>
            disorder but it actually is not that far from the truth.
            As recent studies show, the language you speak has more effects on you than you realize.
            According to the studies, the language a person speaks affects their cognition,
            <suggestion-start name="deletion:suggestion-2:user-1"></suggestion-start>
            feelings, <suggestion-end name="deletion:suggestion-2:user-1"></suggestion-end>
            behavior, emotions and hence <strong>their personality</strong>.
        </p>
        <p>
            This shouldn’t come as a surprise
            <a href="https://en.wikipedia.org/wiki/Lateralization_of_brain_function">since we already know</a>
            that different regions of the brain become more active depending on the activity.
            The structure, information and especially
            <suggestion-start name="attribute:bold|ci1tcnk0lkep:suggestion-3:user-1"></suggestion-start><strong>the
            culture of languages<suggestion-end name="attribute:bold|ci1tcnk0lkep:suggestion-3:user-1"></strong></suggestion-end>
            varies substantially
            and the language a person speaks is an essential element of daily life.
        </p>`
};

```

The Builder’s output sample already provides templates of three plugins: `UsersIntegration`, `CommentsIntegration`, and `TrackChangesIntegration`. Replace them with ones that read the data from `appData` and use the [Users](../../../api/module%5Fcollaboration-core%5Fusers-Users.html), [CommentsRepository](../../../api/module%5Fcomments%5Fcomments%5Fcommentsrepository-CommentsRepository.html), and [TrackChanges](../../../api/track-changes.html) APIs, respectively:

```
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Users' ];
    }

    static get pluginName() {
        return 'UsersIntegration';
    }

    init() {
        const usersPlugin = this.editor.plugins.get( 'Users' );

        // Load the users data.
        for ( const user of appData.users ) {
            usersPlugin.addUser( user );
        }

        // Set the current user.
        usersPlugin.defineMe( appData.userId );
    }
}

class CommentsIntegration extends Plugin {
    static get requires() {
        return [ 'CommentsRepository', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'CommentsIntegration';
    }

    init() {
        const commentsRepositoryPlugin = this.editor.plugins.get( 'CommentsRepository' );

        // Load the comment threads data.
        for ( const commentThread of appData.commentThreads ) {
            commentsRepositoryPlugin.addCommentThread( commentThread );
        }
    }
}

class TrackChangesIntegration extends Plugin {
    static get requires() {
        return [ 'TrackChanges', 'UsersIntegration' ];
    }

    static get pluginName() {
        return 'TrackChangesIntegration';
    }

    init() {
        const trackChangesPlugin = this.editor.plugins.get( 'TrackChanges' );

        // Set the adapter to the `TrackChanges#adapter` property.
        trackChangesPlugin.adapter = {
            getSuggestion: suggestionId => {
                console.log( 'Getting suggestion', suggestionId );

                // Write a request to your database here.
                // The returned `Promise` should be resolved with the suggestion
                // data object when the request has finished.
                switch ( suggestionId ) {
                    case 'suggestion-1':
                        return Promise.resolve( {
                            id: suggestionId,
                            type: 'insertion',
                            authorId: 'user-2',
                            createdAt: new Date(),
                            data: null,
                            attributes: {}
                        } );
                    case 'suggestion-2':
                        return Promise.resolve( {
                            id: suggestionId,
                            type: 'deletion',
                            authorId: 'user-1',
                            createdAt: new Date(),
                            data: null,
                            attributes: {}
                        } );
                    case 'suggestion-3':
                        return Promise.resolve( {
                            id: 'suggestion-3',
                            type: 'attribute:bold|ci1tcnk0lkep',
                            authorId: 'user-1',
                            createdAt: new Date( 2019, 2, 8, 10, 2, 7 ),
                            data: {
                                key: 'bold',
                                oldValue: null,
                                newValue: true
                            },
                            attributes: {
                                groupId: 'e29adbb2f3963e522da4d2be03bc5345f'
                            }
                        } );
                }
            },

            addSuggestion: suggestionData => {
                console.log( 'Suggestion added', suggestionData );

                // Write a request to your database here.
                // The returned `Promise` should be resolved when the request
                // has finished. When the promise resolves with the suggestion data
                // object, it will update the editor suggestion using the provided data.
                return Promise.resolve( {
                    createdAt: new Date()       // Should be set on the server side.
                } );
            },

            updateSuggestion: ( id, suggestionData ) => {
                console.log( 'Suggestion updated', id, suggestionData );

                // Write a request to your database here.
                // The returned `Promise` should be resolved when the request
                // has finished.
                return Promise.resolve();
            }
        };

        // In order to load comments added to suggestions, you
        // should also integrate the comments adapter.
    }
}

```

Update the `editorConfig.root.initialData` property to use `appData.initialData` value:

```
const editorConfig = {
    // ...

    root: {
        initialData: appData.initialData
    }

    // ...
};

```

And build the project:

```
npm run dev

```

You should now we see an editor instance with one comment thread and several track changes suggestions. The adapter is now ready to use with your rich text editor.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--demo-2">

#### Demo

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--tc-adapter-console">

```

```

Since the track changes adapter saves suggestions immediately after they are performed, it is also recommended to use the [Autosave](../../../api/module%5Fautosave%5Fautosave-Autosave.html) plugin to save the editor content after each change.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--why-is-there-no-event-when-i-accept-or-discard-a-suggestion">

#### Why is there no event when I accept or discard a suggestion?

Note that when you discard or accept a suggestion, no event is fired in the adapter. This is because the suggestion is never removed from the editor during the editing session. You are able to restore it using undo (Cmd+Z or Ctrl+Z). The same happens when you remove a paragraph with suggestions – there will be no event fired because no data is really removed.

However, to make sure that you do not keep outdated suggestions in your database, you should do a cleanup when the editor is destroyed or closed. You can compare the suggestions stored in the editor data with the suggestions stored in your database and remove all the suggestions that are no longer in the editor data from your database.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html--track-changes-samples">

### Track changes samples

Please visit the [ckeditor5-collaboration-samples](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master) GitHub repository to find several sample integrations of the track changes feature.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html"</a>

## Preview final content

The content you work on may become heavily edited, including lots of suggestions, possibly coming from different authors. At some point, it may become difficult to understand what the final content will look like, after all suggestions are accepted. When this happens, you may use the track changes preview feature. When used, it will display a modal window with a preview of the content with all the suggestions accepted.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html--demo">

### Demo

Use the “Preview final content” button in the track changes toolbar dropdown  (you can find it in the menu bar, in “Tools -> Track changes” menu). The editor will display a modal window with the preview. Add more suggestions to the document to see how the final content changes.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html--installation">

### Installation

To enable the track changes preview feature, add the `TrackChangesPreview` plugin to your editor setup:

The plugin will add a new “Preview final content” button to the track changes toolbar dropdown and in the “Tools -> Track changes” menu in the menu bar.

You can also execute `previewFinalContent` command to show the modal window with the preview:

```
editor.commands.get( 'previewFinalContent' ).execute();

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html--configuration">

### Configuration

When the preview is opened, the editor content is put inside a container element, which has the same CSS classes as the editor’s editable element. In most cases this is sufficient to replicate the styling of editor content.

If you see that your custom CSS styles are not applied in the preview, make sure that your CSS rules also apply to the HTML in the preview modal. You may need to adjust selectors in your CSS rules to match the preview dialog structure.

By default, the editor content is put into a following DOM structure:

```
<div class="ck ck-track-changes-preview" ...>
    <div class="ck ck-content ck-editor__editable ck-track-changes-preview__root-container ..." data-ck-root-name="main">
        <!-- Editor content goes here. !-->
    </div>
</div>

```

You can target the `ck-track-changes-preview` and `ck-track-changes-preview__root-container` classes, as well as `data-ck-root-name` attribute.

However, some integrations may require a custom DOM structure, for example due to complex CSS rules, or if you use [MultiRootEditor](../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html). To provide a custom DOM structure inside the preview modal dialog, use the `trackChanges.preview.renderFunction` configuration option.

```
{
    trackChanges: {
        preview: {
            renderFunction: ( container, elements ) => {
                // Custom callback inserting the `elements` into `container`.
                // ...
            }
        }
    }
}

```

Two parameters are passed to the callback:

* `container` – the main container element that will be inserted into the modal window (this is the element with the `ck-track-changes-preview` CSS class).
* `elements` – an array of elements, each holding the contents of one of the editor roots. Unless you are using [MultiRootEditor](../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html), there will be only one element available. They are sorted according to their DOM order. Each element has the `data-ck-root-name` attribute set to the corresponding editor’s root name. You can use them for styling purposes, or to recognize a particular root and handle it in some custom way.

Use `renderFunction` to process the `elements` array, wrap them in a DOM structure that will fit your needs, and insert them into `container` element.

Below is an example of how `renderFunction` could be used together with a multi-root editor:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        trackChanges: {
            preview: {
                renderFunction: ( container, elements ) => {
                    for ( const element of elements ) {
                        // Wrap each root into an additional container.
                        const dataContainer = document.createElement( 'div' );

                        dataContainer.classList.add( 'additional-container' );
                        dataContainer.appendChild( element );

                        container.appendChild( dataContainer );
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This will result in the following structure inside the preview modal window:

```
<div class="ck ck-track-changes-preview" ...>
    <div class="additional-container">
        <div class="ck ck-content ck-editor__editable ck-track-changes-preview__root-container ..." data-ck-root-name="root-a">
            <!-- Editor content for "root-a" goes here. !-->
        </div>
    </div>
    <div class="additional-container">
        <div class="ck ck-content ck-editor__editable ck-track-changes-preview__root-container ..." data-ck-root-name="root-b">
            <!-- Editor content for "root-b" goes here. !-->
        </div>
    </div>
    <div class="additional-container">
        <div class="ck ck-content ck-editor__editable ck-track-changes-preview__root-container ..." data-ck-root-name="root-c">
            <!-- Editor content for "root-c" goes here. !-->
        </div>
    </div>
</div>

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html">source file: "ckeditor5/latest/features/collaboration/track-changes/track-changes.html"</a>

## Track changes overview

This feature enables the track changes mode (also known as the suggestion mode) in CKEditor 5\. This way you can follow the history of changes made by different editors as well as easily accept or decline such changes.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--demo">

### Demo

You can test the track changes feature in the editor below. Use the toolbar dropdown  to enable changes tracking and mass accept or decline suggestions. Use the side panel to work with individual changes.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

In this mode, changes done by the users are marked in the content and shown as suggestions in the sidebar. Suggestions can be accepted or discarded by the users. The suggestion balloon is then closed and the change is no longer marked.

Apart from reading this guide, we encourage you to read a dedicated blog post which [compares the track changes with revision history](https://ckeditor.com/blog/ckeditor-5-comparing-revision-history-with-track-changes/) and another blog post discussing [CKEditor 5’s collaboration features and their real-life implementations](https://ckeditor.com/blog/Feature-of-the-month-Collaborative-writing-in-CKEditor-5/).

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--integration">

### Integration

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--use-as-a-standalone-plugin">

#### Use as a standalone plugin

The track changes feature does not require real-time collaboration to work. If you prefer a more traditional approach to document editing, track changes can be added to CKEditor 5 just like any other plugin.

To learn how to integrate track changes as a standalone plugin, please refer to the [Integrating track changes with your application](#ckeditor5/latest/features/collaboration/track-changes/track-changes-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--use-with-real-time-collaboration">

#### Use with real-time collaboration

If you are using the real-time collaboration feature, refer to the [Real-time collaboration features integration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) guide.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--learn-more">

### Learn more

After you run the track changes feature in your editor, you may want to learn more about it. Find out below how it works, how it can be configured, customized, and extended, to fit your application the best way possible.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--configuration">

#### Configuration

The configuration for the track changes feature can be found in the [TrackChangesConfig](../../../api/module%5Ftrack-changes%5Ftrackchangesconfig-TrackChangesConfig.html) API reference.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--suggestions-markup">

#### Suggestions markup

Suggestions are always attached to some place in the document. To make sure that they will not be lost, the track changes plugin adds some special markup to the document:

* `<suggestion-start>` and `<suggestion-end>` tags are added if the suggestion starts/ends in text,
* otherwise, the following attributes are added to elements:  
  * `data-suggestion-start-before`,
  * `data-suggestion-end-after`,
  * `data-suggestion-start-after`,
  * `data-suggestion-end-before`.

Also, the `<suggestion-td>` tag is used for table cells pasting suggestions to separate old content (original) from the new content (pasted).

[Read more about marker-to-data conversion](../../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-markerToData) to understand what data you may expect.

Examples of the possible markup:

Replacing the word “chocolate” with the word “ice-cream”:

```
<p>
    I like
    <suggestion-start name="insertion:e8ghd7:e390dk"></suggestion-start>ice-cream<suggestion-end name="insertion:e8ghd7:e390dk"></suggestion-end>
    <suggestion-start name="deletion:ejd853:e390dk"></suggestion-start>chocolate<suggestion-end name="deletion:ejd853:e390dk"></suggestion-end>.
</p>

```

Inserting image:

```
<figure class="image" data-suggestion-end-after="insertion:e1f0810:eohfu9" data-suggestion-start-before="insertion:e1f0810:eohfu9">
    <img src="foo.jpg">
    <figcaption>Image caption.</figcaption>
</figure>

```

Adding bold:

```
<p>
    This is
    <suggestion-start name="attribute:bold|ci1tcnk0lkep:ekeij:e3404"></suggestion-start>
    <strong>important</strong>
    <suggestion-end name="attribute:bold|ci1tcnk0lkep:ekeij:e3404"></suggestion-end>
    .
</p>

```

Pasting a table cell with the text “New” into a table cell with the text “Old”:

```
<td ...>
    <suggestion-td data-suggestion-end-after="insertion:..." data-suggestion-start-before="insertion:...">
        <p>New</p>
    </suggestion-td>
    <suggestion-td data-suggestion-end-after="deletion:..." data-suggestion-start-before="deletion:...">
        <p>Old</p>
    </suggestion-td>
</td>

```

Note that if your application filters HTML content, for example, to prevent XSS, make sure to leave the suggestion tags and attributes in place when saving the content in the database. The suggestion markup is necessary for further editing sessions.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--suggestions-attributes">

#### Suggestions attributes

Suggestion attributes is additional data stored with the suggestions and used by other features. You can also use them to set and read custom data necessary by your custom features built around suggestions.

```
suggestion.setAttribute( 'isImportant', true );

```

You can group multiple values in an object, using dot notation:

```
suggestion.setAttribute( 'customData.type', 'image' );
suggestion.setAttribute( 'customData.src', 'foo.jpg' );

```

Attributes set on the suggestion can be accessed through `attribute` property:

```
const isImportant = suggestion.attributes.isImportant;
const type = suggestion.attributes.customData.type;

```

You can also observe `attributes` property or bind other properties to it:

```
myObj.bind( 'customData' ).to( suggestion, 'attributes', attributes => attributes.customData );

```

Whenever [setAttribute()](../../../api/module%5Ftrack-changes%5Fsuggestion-Suggestion.html#function-setAttribute) or [removeAttribute()](../../../api/module%5Ftrack-changes%5Fsuggestion-Suggestion.html#function-removeAttribute) is called, the `attributes` property is re-set, and observables are refreshed. Using these fires the `update` method in an adapter.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--saving-the-data-without-suggestions">

#### Saving the data without suggestions

If you need to get the editor data with all the existing suggestions accepted or discarded, please refer to the [dedicated guide](#ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html).

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--saving-the-data-with-suggestion-highlights">

#### Saving the data with suggestion highlights

By default, the data returned by `editor.getData()` contains the markup for the suggestions as described above. It does not provide the markup that visually shows the suggestion highlights in the data (similarly to how they are shown in the editor).

It is possible to change the editor output using the `showSuggestionHighlights` option passed in `editor.getData()`. When set, the editor output will return suggestions similarly to how they are present inside the editor:

```
editor.getData( { showSuggestionHighlights: true } );

```

Will return:

```
<p>
    <span class="ck-suggestion-marker ck-suggestion-marker-formatInline">
        Foo
    </span>
    bar
</p>

```

The [export to PDF feature](#ckeditor5/latest/features/converters/export-pdf.html) can be integrated with the suggestion highlights as shown below:

```
{
    exportPdf: {
        // More configuration of the Export to PDF.
 		// ...
        dataCallback: editor => editor.getData( {
            showSuggestionHighlights: true
        } )
    }
}

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--force-track-changes-mode-to-be-enabled">

#### Force track changes mode to be enabled

If you would like to have track changes enabled by default, execute the `trackChanges` command, which toggles the track changes mode. It should be done after the editor instance is initialized:

```
ClassicEditor
    .create( {
       // Editor's configuartion.
 		// ...
    } )
    .then( editor => {
        editor.execute( 'trackChanges' );
    } )
    .catch( error => console.error( error ) );

```

You can disable the `trackChanges` command to prevent turning the track changes on or off. This can be useful for example when a particular user has permissions only to create suggestions in a given document. You can disable the command by calling [Command#forceDisabled()](../../../api/module%5Fcore%5Fcommand-Command.html#function-forceDisabled):

```
ClassicEditor
    .create( {
        // Editor's configuartion.
        // ...
    } )
    .then( editor => {
        editor.execute( 'trackChanges' );

        editor.commands.get( 'trackChanges' ).forceDisabled( 'suggestionsMode' );
    } )
    .catch( error => console.error( error ) );

```

To prevent a user from accepting or discarding suggestions, disable commands responsible for these actions:

```
ClassicEditor
    .create( {
        // Editor's configuartion.
        // ...
    } )
    .then( editor => {
        editor.execute( 'trackChanges' );

        editor.commands.get( 'trackChanges' ).forceDisabled( 'suggestionsMode' );
        editor.commands.get( 'acceptSuggestion' ).forceDisabled( 'suggestionsMode' );
        editor.commands.get( 'acceptAllSuggestions' ).forceDisabled( 'suggestionsMode' );
        editor.commands.get( 'discardAllSuggestions' ).forceDisabled( 'suggestionsMode' );
        editor.commands.get( 'discardSuggestion' ).forceDisabled( 'suggestionsMode' );
    } )
    .catch( error => console.error( error ) );

```

Keep in mind that the `'suggestionsMode'` identifier can be later used to enable commands using [Command#clearForceDisabled()](../../../api/module%5Fcore%5Fcommand-Command.html#function-clearForceDisabled).

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--markers-styling">

#### Markers styling

Similarly to everywhere in the CKEditor 5 Ecosystem, we have used [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables) to let the developers customize the design of such UI elements as, for example, suggestion markers. You can override these properties with a `.css` file or place your customizations directly into the `<head>` section of your page, but in this case, you will need to use a more specific CSS selector than `:root` (like `<body>`).

Here you can find the default CSS Variables used for the track changes feature:

```
:root {
    /* You can override the design of suggestion markers in the content. */

    /* Variables responsible for suggestions for text: */
    --ck-color-suggestion-marker-insertion-border: hsla(128, 71%, 40%, .35);
    --ck-color-suggestion-marker-insertion-border-active: hsla(128, 71%, 25%, .5);
    --ck-color-suggestion-marker-insertion-background: hsla(128, 71%, 65%, .35);
    --ck-color-suggestion-marker-insertion-background-active: hsla(128, 71%, 50%, .5);

    --ck-color-suggestion-marker-deletion-border: hsla(345, 71%, 40%, .35);
    --ck-color-suggestion-marker-deletion-border-active: hsla(345, 71%, 25%, .5);
    --ck-color-suggestion-marker-deletion-background: hsla(345, 71%, 65%, .35);
    --ck-color-suggestion-marker-deletion-background-active: hsla(345, 71%, 50%, .5);
    --ck-color-suggestion-marker-deletion-stroke: hsla(345, 71%, 20%, .5);

    --ck-color-suggestion-marker-format-border: hsla(191, 90%, 40%, .4);
    --ck-color-suggestion-marker-format-border-active: hsla(191, 90%, 40%, .65);

    /* Variables responsible for the left border of the suggestion boxes in the sidebar: */
    --ck-color-comment-box-border: hsl(55, 98%, 48%);
    --ck-color-suggestion-box-deletion-border: hsl(345, 62%, 60%);
    --ck-color-suggestion-box-insertion-border: hsl(128, 62%, 60%);
    --ck-color-suggestion-box-format-border: hsl(191, 62%, 60%);

    /* Variables responsible for the styling of suggestions for widgets: */
    --ck-color-suggestion-widget-insertion-background: hsla(128, 71%, 65%, .05);
    --ck-color-suggestion-widget-insertion-background-active: hsla(128, 71%, 50%, .07);
    --ck-color-suggestion-widget-deletion-background: hsla(345, 71%, 65%, .05);
    --ck-color-suggestion-widget-deletion-background-active: hsla(345, 71%, 45%, .07);
    --ck-color-suggestion-widget-format-background: hsla(191, 90%, 40%, .09);
    --ck-color-suggestion-widget-format-background-active: hsla(191, 90%, 40%, .16);

    --ck-color-suggestion-widget-th-insertion-background: hsla(128, 71%, 65%, .1);
    --ck-color-suggestion-widget-th-insertion-background-active: hsla(128, 71%, 50%, .12);
    --ck-color-suggestion-widget-th-deletion-background: hsla(345, 71%, 65%, .1);
    --ck-color-suggestion-widget-th-deletion-background-active: hsla(345, 71%, 45%, .12);
}

```

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--api-overview">

#### API overview

Check the [track changes API documentation](../../../api/track-changes.html) for detailed information about the track changes API. Making yourself familiar with the API may help you understand the code snippets.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--suggestions-annotations-customization">

#### Suggestions annotations customization

The suggestions annotations are highly customizable. Please refer to the [Annotation customization](#ckeditor5/latest/features/collaboration/annotations/annotations.html) guide to learn more.

<a id="ckeditor5/latest/features/collaboration/track-changes/track-changes.html--integration-with-custom-features">

#### Integration with custom features

If you provide your own plugins, you may want to [integrate these custom features with track changes mode](#ckeditor5/latest/features/collaboration/track-changes/track-changes-custom-features.html).

<a id="ckeditor5/latest/features/collaboration/users.html">source file: "ckeditor5/latest/features/collaboration/users.html"</a>

## Users

The [Users](../../api/module%5Fcollaboration-core%5Fusers-Users.html) plugin and related plugins let you manage user data and permissions. This is essential when many users are working on the same document.

<a id="ckeditor5/latest/features/collaboration/users.html--additional-feature-information">

### Additional feature information

The users plugin is automatically provided if you load any collaboration features plugins.

You must set the users data before you load the collaboration features. To do that, create a plugin that requires all collaboration features you use and defines the users.

```
// An example of a plugin that provides user data for an editor
// that uses the `Comments` and `RevisionHistory` plugins.
class UsersIntegration extends Plugin {
    static get requires() {
        return [ 'Comments', 'RevisionHistory' ];
    }

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );
    }
}

// More code.
// ...

ClassicEditor
    .create( {
        extraPlugins: [ UsersIntegration ],
        // More editor's configuration.
        // ...
    } );

```

<a id="ckeditor5/latest/features/collaboration/users.html--local-user-me-user">

### Local user (“me” user)

A local user (also called “me” user) is regarded as the one who uses the editor instance. Features (like comments or revisions history) will attribute changes to that user.

You can access the “me” user via `Users` plugin:

```
    const usersPlugin = editor.plugins.get( 'Users' );

    // We get either `User` or `undefined` if the local user is not set.
    const localUser = usersPlugin.me;

```

You can also use the `isMe` flag on the `User` item to check if it is the local user:

```
    const id = 'e1d1a156789abc92e4b9affff124455bb';
    const user = editor.plugins.get( 'Users' ).getUser( id );

    // It is `true` if it is the "me" user, `false` otherwise.
    const isOwnUser = user.isMe;

```

The local user’s avatar is highlighted in all places it is displayed. You can easily override this behavior using the `.ck-user_me` CSS class selector.

```
    /* Display the local user the same as other users. */
    .ck-user.ck-user_me {
        border: none;
        outline: none;
    }

```

<a id="ckeditor5/latest/features/collaboration/users.html--anonymous-user">

### Anonymous user

If for some reason you do not want to, or you cannot, provide the user data, you can use the anonymous user:

```
const usersPlugin = editor.plugins.get( 'Users' );

usersPlugin.useAnonymousUser();

usersPlugin.me.name; // 'Anonymous'
usersPlugin.me.id; // 'anonymous-user'

```

The anonymous user’s avatar is a contour of a human face.

You can set the anonymous user’s ID using the `config.users.anonymousUserId` property:

```
ClassicEditor
    .create( {
        // More editor's configuration.
        // ...
        users: {
            anonymousUserId: '0'
        }
    } );

```

<a id="ckeditor5/latest/features/collaboration/users.html--user-permissions">

### User permissions

In many applications, the document creation workflow consists of several precisely defined steps such as content creation, discussion, proofreading, final review and acceptance, etc. The users of such an application may have certain roles and permissions.

You can change the permissions for a given user, which results in enabling or disabling some editor functionalities.

You can set the permissions using the [Permissions](../../api/module%5Fcollaboration-core%5Fpermissions-Permissions.html) plugin. It is automatically provided if you load any of the collaboration features plugins.

It is a good practice to set permissions directly after defining the users:

```
class UsersIntegration extends Plugin {
    // More methods.
    // ...

    init() {
        const users = this.editor.plugins.get( 'Users' );

        // Provide user data from your database.
        users.addUser( {
            id: 'u1',
            name: 'Zee Croce'
        } );

        users.addUser( {
            id: 'u2',
            name: 'Mex Haddox'
        } );

        // Define the local user.
        users.defineMe( 'u1' );

        // Set permissions.
        const permissions = this.editor.plugins.get( 'Permissions' );

        // "Commentator" role.
        permissions.setPermissions( [
            'comment:write'
        ] );
    }
}

```

The full list of defined permissions is available in the [Permissions](../../api/module%5Fcollaboration-core%5Fpermissions-Permissions.html) plugin description.

<a id="ckeditor5/latest/features/collaboration/users.html--operation-authors">

### Operation authors

The [Users#getOperationAuthor()](../../api/module%5Fcollaboration-core%5Fusers-Users.html#function-getOperationAuthor) method gives you the ability to check which user created a given operation. This is useful when creating custom features in integrations using [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html).

There are two cases when the operation author might be `null`:

1. For initial operations (fetched from the server when connecting).
2. For some automatically created operations that are not meaningful (`NoOperation`s).

Below is an example of using `getOperationAuthor()` to find out which user was the last to edit the document. In this case, you should skip `NoOperation`s and some `MarkerOperation`s since they do not affect the document content.

```
let lastUser = null;

editor.model.on( 'applyOperation', ( evt, args ) => {
    const users = editor.plugins.get( 'Users' );
    const operation = args[ 0 ];

    if ( operation.isDocumentOperation && affectsData( operation ) ) {
        const user = users.getOperationAuthor( operation );

        if ( user && user != lastUser ) {
            lastUser = user;

            console.log( lastUser.name, lastUser, operation );
        }
    }

    function affectsData( operation ) {
        return operation.type != 'noop' && ( operation.type != 'marker' || operation.affectsData );
    }
} );

```

<a id="ckeditor5/latest/features/collaboration/users.html--customize-initials">

### Customize initials

To customize how [user initials](../../api/module%5Fcollaboration-core%5Fusers-User.html#member-initials) are generated, set the [getInitialsCallback](../../api/module%5Fcollaboration-core%5Fconfig-CollaborationUsersConfig.html#member-getInitialsCallback) configuration option when initializing the editor:

```
ClassicEditor
    .create( {
        // More editor's configuration.
        // ...
        users: {
            getInitialsCallback: ( name: string ) => {
                // Custom logic to generate initials.
                return name.split( ' ' )[ 0 ].charAt( 0 ) + name.split( ' ' )[ 1 ].charAt( 0 );
            }
        }
    } );

```

<a id="ckeditor5/latest/features/collaboration/users.html--theme-customization">

### Theme customization

<a id="ckeditor5/latest/features/collaboration/users.html--user-avatar">

#### User avatar

You can define the user’s avatar appearance by modifying these CSS variables:

```
:root {
    --ck-user-avatar-size: 40px;
    --ck-user-avatar-background: hsl(210, 52%, 44%);
    --ck-user-name-color: hsl(0, 0%, 100%);

    /* Border color used to highlight the local user. */
    --ck-user-me-border-color: hsl(0, 0%, 100%);
}

```

<a id="ckeditor5/latest/features/collaboration/users.html--user-colors">

#### User colors

You can also define colors used to represent the selection of other users.

User colors are defined using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables). There are 8 user colors defined by default. You can add more colors or change the default colors.

Color variables with an alpha channel (`--ck-user-colors--$(number)-alpha`) are used for selection highlights. The solid color variables (`--ck-user-colors--$(number)`) are used in the rest of the user UI elements. You are welcome to change this color palette to fit your UI.

```
/* The current color set for users in the collaboration plugins. */
:root {
    --ck-user-colors--0: hsla(235, 73%, 67%, 1);
    --ck-user-colors--0-alpha: hsla(235, 73%, 67%, 0.15);

    --ck-user-colors--1: hsla(173, 100%, 24%, 1);
    --ck-user-colors--1-alpha: hsla(173, 100%, 24%, 0.15);

    --ck-user-colors--2: hsla(0, 46%, 50%, 1);
    --ck-user-colors--2-alpha: hsla(0, 46%, 50%, 0.15);

    --ck-user-colors--3: hsla(256, 54%, 45%, 1);
    --ck-user-colors--3-alpha: hsla(256, 54%, 45%, 0.15);

    --ck-user-colors--4: hsla(95, 50%, 36%, 1);
    --ck-user-colors--4-alpha: hsla(95, 50%, 36%, 0.15);

    --ck-user-colors--5: hsla(336, 78%, 43%, 1);
    --ck-user-colors--5-alpha: hsla(336, 78%, 43%, 0.15);

    --ck-user-colors--6: hsla(0, 80%, 59%, 1);
    --ck-user-colors--6-alpha: hsla(0, 80%, 59%, 0.15);

    --ck-user-colors--7: hsla(184, 90%, 43%, 1);
    --ck-user-colors--7-alpha: hsla(184, 90%, 43%, 0.15);
}

```

These colors are, among others, used in the [users presence list](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--users-presence-list) to represent users.

<a id="ckeditor5/latest/features/collaboration/users.html--adding-more-user-colors">

#### Adding more user colors

You can define additional colors for users if you find the default set too small.

First, prepare a CSS file with some color definitions:

```
/* mycolors.css */

:root {
    --ck-user-colors--8: hsla(31, 90%, 43%, 1);
    --ck-user-colors--8-alpha: hsla(31, 90%, 43%, 0.15);

    --ck-user-colors--9: hsla(61, 90%, 43%, 1);
    --ck-user-colors--9-alpha: hsla(61, 90%, 43%, 0.15);
}

```

Then, import this CSS file and specify the `colorsCount` configuration option:

```
import './mycolors.css';

ClassicEditor
    .create( {
        // More editor's configuration.
        // ...
        users: {
            colorsCount: 10
        }
    } );

```

<a id="ckeditor5/latest/features/converters/export-pdf.html">source file: "ckeditor5/latest/features/converters/export-pdf.html"</a>

## Export to PDF

The export to PDF feature lets you generate a PDF file directly from the editor.

<a id="ckeditor5/latest/features/converters/export-pdf.html--demo">

### Demo

The demo below lets you generate a PDF file based on the editor’s content. Edit the document, then click the export to PDF toolbar button  to save the content as a PDF.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/converters/export-pdf.html--how-it-works">

### How it works

The PDF export feature collects the HTML [generated with the editor.getData() method](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-dataCallback) and the [default editor content styles](#ckeditor5/latest/getting-started/setup/css.html) combined with the styles provided by you in the configuration. It then sends them to the CKEditor Cloud Services HTML to PDF converter service. The service generates a PDF file and returns it to the user’s browser so they can save it in the PDF format on their disk.

The crucial aspect of this feature is its [configuration](#ckeditor5/latest/features/converters/export-pdf.html--configuration). To ensure that the generated PDF looks as close as possible to the same content displayed in the WYSIWYG editor, the feature must be carefully configured.

The complementary [pagination feature](#ckeditor5/latest/features/pagination/pagination.html) allows you to see where page breaks would be after you export the document to PDF. Thanks to the live preview, the user can fine-tune the structure of the output document when editing it. The pagination feature also shows you the page count and lets you navigate between the document pages.

<a id="ckeditor5/latest/features/converters/export-pdf.html--integration-with-merge-fields-content-placeholders">

### Integration with merge fields (content placeholders)

Merge fields are visually distinct placeholder elements you can put into the content to mark places where real values should be inserted. It is perfect for creating document templates and other kinds of personalized content. This allows for automation and creating batch output of personalized PDF files. Learn how to configure it in the [proper section of the merge fields guide](#ckeditor5/latest/features/merge-fields.html--using-callbacks-to-define-values).

<a id="ckeditor5/latest/features/converters/export-pdf.html--before-you-start">

### Before you start

After you select a plan, follow the steps below, as explained in the [Export to PDF quick start guide](#cs/latest/guides/export-to-pdf/quick-start.html):

* [Log into the CKEditor Ecosystem customer dashboard](#cs/latest/guides/export-to-pdf/quick-start.html--log-in-to-the-customer-portal).
* [Create the token endpoint needed for authorization](#cs/latest/guides/export-to-pdf/quick-start.html--creating-token-endpoint).
* [Install](#ckeditor5/latest/features/converters/export-pdf.html--installation) and [configure](#ckeditor5/latest/features/converters/export-pdf.html--configuration) the CKEditor 5 export to PDF plugin.

<a id="ckeditor5/latest/features/converters/export-pdf.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/converters/export-pdf.html--configuration">

### Configuration

The configuration is the key to allow the HTML to PDF converter service to generate PDF documents that look as close as possible to the content created in the rich-text editor.

The configuration consists of 3 main parts:

* The [converter options](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-converterOptions) that tell the HTML to PDF converter service what is the format of the page (A4, Letter), the page orientation, etc.
* The [style sheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets) sent to the service. They allow styling the content in the PDF document with the same styles that are applied to the content in the editor.
* The [content styles used in the editor](#ckeditor5/latest/getting-started/setup/css.html) when rendered on the page.

These options need to stay in sync. For example:

* The style sheets sent to the service must define the same typography that is used in the editor.
* The editor’s content container should be styled in a way that reflects the page size and margins defined in the converter options.
* All web fonts defined on the page where the editor is used must be sent to the service as well.

Read on to learn how to achieve this.

<a id="ckeditor5/latest/features/converters/export-pdf.html--default-configuration">

#### Default configuration

This is the default configuration of the PDF export feature for CKEditor 5.

```
{
    exportPdf: {
        fileName: 'document.pdf',
        converterUrl: 'https://pdf-converter.cke-cs.com/v2/convert/html-pdf',
        stylesheets: [
            './ckeditor5-content.css'
        ],
        converterOptions: {
            document: {
                size: 'A4',
                orientation: 'portrait',
                margins: {
                    top: '0mm',
                    bottom: '0mm',
                    right: '0mm',
                    left: '0mm'
                }
            },
            rendering: {
                wait_for_network: true,
                wait_time: 0
            }
        },
        dataCallback: ( editor ) => editor.getData()
    }
}

```

If you are using the EU cloud region, remember to adjust the endpoint:

```
exportPdf: {
    converterUrl: 'https://pdf-converter.cke-cs-eu.com/v2/convert/html-pdf'
}

```

<a id="ckeditor5/latest/features/converters/export-pdf.html--stylesheets-option">

#### `stylesheets` option

Use the `stylesheets` option to provide paths (relative or absolute URLs) to all style sheets that should be included during the HTML to PDF conversion.

The rule of thumb is if you want the export to preserve the styles, always add the style sheets with the content styles of the editor. Their path depends on your application setup, for example:

```
{
    exportPdf: {
        stylesheets: [
            './ckeditor5-content.css'
            './styles.css'
        ],
        // ...
    }
}

```

In the snippet above, we assume both style sheets are available via the relative path on the client side. For example, some frameworks allow to place files in the `public` folder.

<a id="ckeditor5/latest/features/converters/export-pdf.html--plugin-options">

#### Plugin options

For some use cases the default configuration will suffice. As you can see in the example above, you can improve how your PDF file will look by adjusting the PDF export plugin configuration.

* **[config.exportPdf.stylesheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets)**  
You can set the paths (relative or absolute URLs) to the style sheets that should be included during the HTML to PDF conversion.
* **[config.exportPdf.fileName](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-fileName)**  
Sets the name for the generated PDF file (together with the extension). The default name is `document.pdf`. You can see it called in the [default configuration](#ckeditor5/latest/features/converters/export-pdf.html--default-configuration) listing above.  
This option, however, also allows for using a callback to generate a dynamic file name. In the example below, the document’s title will be used as the file name of the generated PDF file.  
```  
// Dynamic file name.  
const exportPdfConfig = {  
    fileName: () => {  
        const articleTitle = document.querySelector( '#title' );  
        return `${ articleTitle.value }.pdf`;  
    }  
}  
```
* **[config.exportPdf.converterUrl](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-converterUrl)**  
By default, the PDF export feature is configured to use the CKEditor Cloud Services HTML to PDF converter service to generate the PDF files. You can, however, use this option to provide the URL to an on-premises converter. [Contact us](https://ckeditor.com/contact/) if you need this feature.  
If you are using the EU cloud region, adjust the endpoint accordingly:  
```  
exportPdf: {  
    converterUrl: 'https://pdf-converter.cke-cs-eu.com/v2/convert/html-pdf'  
}  
```
* **[config.exportPdf.tokenUrl](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-tokenUrl)**  
A token URL or a token request function. This field is optional and you should use it when you require a different [tokenUrl](../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) for the export to PDF feature. You can skip this option if you use the `cloudServices` configuration to provide the same `tokenUrl`. In most cases you will probably want to provide the token in `cloudServices`, as other plugins like [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) will use this token as well. In this guide, to explicitly show that this value is needed, we leave it the inside `exportPdf` configuration.
* **[config.exportPdf.converterOptions](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-converterOptions)**  
The converter options control the PDF output: page size, margins, headers, footers, metadata, security, and more. See the [HTML to PDF Converter features](#ckeditor5/latest/features/converters/export-pdf.html--html-to-pdf-converter-features) section for details on each capability, or refer to the [API documentation](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConverterOptionsV2.html) for the full reference. Below is a sample configuration:  
```  
converterOptions: {  
    document: {  
        size: 'A4',  
        orientation: 'portrait',  
        margins: {  
            top: '20mm',  
            bottom: '20mm',  
            right: '12mm',  
            left: '12mm'  
        }  
    }  
}  
```
* **[config.exportPdf.dataCallback](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-dataCallback)**  
By default, the plugin uses `editor.getData()` to gather the HTML sent to the conversion service. You can use this option to customize the editor’s data. For example, use this setting to enable [highlighting tracked changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) and [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) in the exported PDF file.  
```  
    dataCallback: editor => editor.getData( {  
        showSuggestionHighlights: true,  
        showCommentHighlights: true  
    } ),  
```

<a id="ckeditor5/latest/features/converters/export-pdf.html--export-to-pdf-v1-deprecated">

#### Export to PDF V1 (deprecated)

The V1 API uses a flat configuration structure for `converterOptions`, unlike the nested structure in V2:

```
{
    exportPdf: {
        version: 1, // Required to use V1
        converterOptions: {
            format: 'A4',
            margin_top: '0mm',
            margin_bottom: '0mm',
            margin_right: '0mm',
            margin_left: '0mm',
            page_orientation: 'portrait',
            header_html: '<div class="styled">Header content</div>',
            footer_html: '<div class="styled-counter"><span class="pageNumber"></span></div>',
            header_and_footer_css: '#header, #footer { background: hsl(0, 0%, 95%); } .styled { font-weight: bold; } .styled-counter { font-size: 1em; }',
            wait_for_network: true,
            wait_time: 0
        }
    }
}

```

For the complete list of V1 options, see the [V1 API documentation](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConverterOptions.html) and the [V1 REST API documentation](https://pdf-converter.cke-cs.com/v1/convert/docs).

<a id="ckeditor5/latest/features/converters/export-pdf.html--html-to-pdf-converter-features">

### HTML to PDF converter features

<a id="ckeditor5/latest/features/converters/export-pdf.html--page-setup">

#### Page setup

Configure the page size, orientation, and margins through the `document` object in `converterOptions`:

```
converterOptions: {
    document: {
        size: 'A4',
        orientation: 'portrait',
        margins: {
            top: '20mm',
            bottom: '20mm',
            left: '15mm',
            right: '15mm'
        }
    }
}

```

The `size` property accepts predefined formats (`'A4'`, `'Letter'`, `'Legal'`, `'A3'`, etc.) or a custom object with `width` and `height`. For a complete example including matching editor CSS, see [Setting the page format](#ckeditor5/latest/features/converters/export-pdf.html--setting-the-page-format).

```
document: {
    size: { width: '210mm', height: '297mm' }
}

```

<a id="ckeditor5/latest/features/converters/export-pdf.html--setting-the-base-url">

#### Setting the base URL

To enable proper resolution of relative URLs for images and links, pass the `base_url` option:

```
converterOptions: {
    base_url: 'https://example.com'
}

```

For editor content like:

```
<p><a href="/">Homepage</a></p>
<p><img src="/logo.png" alt="Logo"></p>

```

this option will resolve the URLs into their absolute forms:

* `/` will become `https://example.com`,
* `/logo.png` will become `https://example.com/logo.png`.

<a id="ckeditor5/latest/features/converters/export-pdf.html--images">

#### Images

Currently, the converter only supports absolute URLs and `Base64`\-encoded images. See the [REST API documentation](https://pdf-converter.cke-cs.com/v2/convert/docs) for details.

<a id="ckeditor5/latest/features/converters/export-pdf.html--web-fonts">

#### Web fonts

If you are using web fonts via an `@import` or `@font-face` declaration, you can pass the path(s) to the `.css` file(s) containing them to the [config.exportPdf.stylesheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets). The order of the provided paths matters – you should list style sheets with web font declarations first. For more technical details, check the [API documentation](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html) and [REST API documentation](https://pdf-converter.cke-cs.com/v2/convert/docs).

<a id="ckeditor5/latest/features/converters/export-pdf.html--rendering-options">

#### Rendering options

Fine-tune how the converter renders the page before generating the PDF:

```
converterOptions: {
    rendering: {
        wait_for_network: true,
        wait_time: 0,
        wait_for_selector: '.content-loaded'
    }
}

```

* `wait_for_network` – When `true`, the converter waits for all network requests to finish before rendering.
* `wait_time` – Additional wait time in milliseconds (0–15000) after the page loads.
* `wait_for_selector` – A CSS selector; the converter waits until an element matching this selector appears in the DOM.

<a id="ckeditor5/latest/features/converters/export-pdf.html--headers-and-footers">

#### Headers and footers

The converter lets you set the document’s header and footer similarly to Microsoft Word or Google Docs. Define a `default` header and footer applied to all pages:

```
converterOptions: {
    document: {
        margins: {
            top: '15mm',
            bottom: '15mm',
            right: '15mm',
            left: '15mm'
        }
    },
    headers: {
        default: {
            html: '<div class="styled">Header content</div>',
            css: '#header { background: hsl(0, 0%, 95%); } .styled { font-weight: bold; text-align: center; }'
        }
    },
    footers: {
        default: {
            html: '<div class="styled-counter"><span class="pageNumber"></span></div>',
            css: '#footer { background: hsl(0, 0%, 95%); } .styled-counter { font-size: 1em; color: hsl(0, 0%, 60%); }'
        }
    }
}

```

You can set a background for the header or footer using the `#header` or `#footer` selector in the `css` option. These wrapper elements are provided by the converter.

<a id="ckeditor5/latest/features/converters/export-pdf.html--per-page-type-headers-and-footers">

##### Per-page-type headers and footers

You can define different headers and footers for the first page, odd pages, and even pages using the `first`, `odd`, and `even` keys. Each overrides the `default` for its respective pages:

```
headers: {
    default: {
        html: '<div class="header">Company Name</div>',
        css: '.header { text-align: center; font-size: 10pt; }'
    },
    first: {
        html: '<div class="header-first">Report Title</div>',
        css: '.header-first { text-align: center; font-size: 14pt; font-weight: bold; }'
    },
    odd: {
        html: '<div class="header-odd">Section <span class="pageNumber"></span></div>',
        css: '.header-odd { text-align: right; }'
    },
    even: {
        html: '<div class="header-even"><span class="pageNumber"></span> Section</div>',
        css: '.header-even { text-align: left; }'
    }
}

```

The `footers` object follows the same structure. If a page type key is not defined, the `default` is used as a fallback.

As you can see in the examples above, you can use the `pageNumber` and `totalPages` placeholders. For more details, refer to the [REST API documentation](https://pdf-converter.cke-cs.com/v2/convert/docs).

If you import headers and footers from a Word document and want to preserve and reapply them when exporting, see the Import from Word guide’s [Preserving headers and footers](#ckeditor5/latest/features/converters/import-word/import-word.html--preserving-headers-and-footers). Note that when forwarding stored headers/footers into PDF export, you typically need to inject those header/footer converter options within the `execute` call of the `exportPdf` command. Hence, the converter receives them at export time.

<a id="ckeditor5/latest/features/converters/export-pdf.html--mirror-margins">

#### Mirror margins

Mirror margins (also known as “gutter” or “book” margins) are useful for documents intended for double-sided printing or binding. When `enable_mirror_margins` is set to `true`, the left and right margins swap between odd and even pages:

* **Odd pages (right-hand)**: `left` becomes the inner margin (near binding), `right` becomes the outer margin.
* **Even pages (left-hand)**: the margins are reversed – `right` becomes the inner margin, `left` becomes the outer margin.

```
converterOptions: {
    document: {
        margins: {
            top: '20mm',
            bottom: '20mm',
            left: '25mm',
            right: '15mm',
            enable_mirror_margins: true
        }
    }
}

```

In this example, odd pages will have a 25 mm inner margin and 15 mm outer margin, while even pages will swap to 15 mm inner and 25 mm outer, creating a mirrored layout suitable for book binding.

<a id="ckeditor5/latest/features/converters/export-pdf.html--document-metadata">

#### Document metadata

Set PDF properties such as title, author, subject, keywords, and custom fields. PDF readers display this information in their document properties panel.

```
converterOptions: {
    metadata: {
        title: 'Quarterly Report',
        author: 'Jane Smith',
        subject: 'Q1 2026 Financial Summary',
        keywords: [ 'finance', 'quarterly', 'report' ],
        custom_fields: {
            'Department': 'Marketing',
            'Document-ID': 'DOC-12345'
        }
    }
}

```

<a id="ckeditor5/latest/features/converters/export-pdf.html--security-and-encryption">

#### Security and encryption

Protect generated PDFs with an owner password. The owner password controls document permissions (printing, copying, modifying). The PDF is encrypted with AES-256 by default.

```
converterOptions: {
    security: {
        owner_password: 'securePassword123'
    }
}

```

The `owner_password` is required when using this feature and must be between 6 and 64 characters.

<a id="ckeditor5/latest/features/converters/export-pdf.html--digital-signatures">

#### Digital signatures

Sign documents with PKCS#12 certificates to verify authenticity. The signature is embedded invisibly in the PDF metadata – it does not add visual elements to the document pages. PDF readers will show signature details in their signature panel.

```
converterOptions: {
    signature: {
        certificate: 'base64EncodedPKCS12Certificate',
        certificate_password: 'certificatePassword',
        reason: 'Document approval',
        location: 'New York, USA'
    }
}

```

Both `certificate` (base64-encoded `.p12`/`.pfx` file) and `certificate_password` are required. The `reason` and `location` fields are optional metadata.

<a id="ckeditor5/latest/features/converters/export-pdf.html--compression-control">

#### Compression control

By default, the converter compresses PDF output for smaller file sizes. You can disable compression to preserve the original PDF structure:

```
converterOptions: {
    disable_compression: true
}

```

<a id="ckeditor5/latest/features/converters/export-pdf.html--other">

#### Other

* By default, the generated PDF file is encoded with **`UTF-8`**.
* By default, the converter sets **`color-adjust: exact;`**. This means that your PDF document will preserve colors, images, and styles as you can see them in the editor.
* The generated document can be watermarked. [See the example and demo in the section below.](#ckeditor5/latest/features/converters/export-pdf.html--adding-a-watermark-to-the-document)

<a id="ckeditor5/latest/features/converters/export-pdf.html--examples">

### Examples

Check out some configuration examples that will show you how to customize the export to PDF feature. In the first example, you will learn how to add custom styling. The second example will show you how to set the page format. In the third one, you can see how to use web fonts in your configuration.

<a id="ckeditor5/latest/features/converters/export-pdf.html--re-using-custom-editor-styling">

#### Re-using custom editor styling

The default configuration of the [ExportPdf](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdf.html) plugin attaches the default editor content styles to the HTML content sent to the converter.

However, if you need to, you can also set paths to additional CSS files. Let us assume that you already have a `my-custom-editor-styles.css` with your custom styling for the editor content that you use on your website, but you also want to include these styles in the generated PDF file.

Here is the example code:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportPdf: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.pdf'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );


```

This is how the corresponding editor styles may look like:

```
/* my-custom-editor-styles.css */

/* Custom link color. */
.ck.ck-content a {
    color: purple;
}

/* Custom header styling. */
.ck.ck-content h1 {
    border-bottom: 2px solid;
}

/* Another custom styling... */
/* ... */

```

With these settings, the content in the generated PDF file should have the same styling as it has in the WYSIWYG editor.

<a id="ckeditor5/latest/features/converters/export-pdf.html--setting-the-page-format">

#### Setting the page format

Consistency is an important factor. To make sure that the editor content and the generated PDF file look the same, you need to match their format settings. You can change your existing style sheet or use a new one, for example, `format.css`. By default, the CKEditor Cloud Services HTML to PDF converter is set to A4 format, but you may change this setting in your configuration.

Assuming that you want to create a document in the US Letter format, with the standard margins (`19mm` for each side), here is the example code you can use:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportPdf: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.pdf',
            converterOptions: {
                document: {
                    // Document format settings with proper margins.
                    size: 'Letter',
                    orientation: 'portrait',
                    margins: {
                        top: '19mm',
                        bottom: '19mm',
                        right: '19mm',
                        left: '19mm'
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Now set the corresponding editor styles:

```
/* format.css */

/* Styles for the editable. */
.ck.ck-content.ck-editor__editable {
    /* US Letter size. */
    width: 215.9mm;
    /* Padding is your document's margin. */
    padding: 19mm;
    /* You do not want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

```

With these settings, the content in the generated PDF file should have the same US Letter format layout as it has in the editor.

<a id="ckeditor5/latest/features/converters/export-pdf.html--providing-web-font-styles">

#### Providing web font styles

This time you want to add a web font to your plugin. Let us assume that the editor is used on a page with certain typography, so the content in the editor inherits the font styles from the page. As such, these styles need to be passed to the HTML to PDF converter service.

The example below uses a web font from the Google Fonts service. For your convenience, the `@import` declaration and any font styles needed for your website are kept in a separate file, for example, `fonts.css`.

```
/* fonts.css */

@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');

html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* ... */

```

This allows you to use the web font settings in the plugin, without any additional tweaks. Just pass the path to the file in the [config.exportPdf.stylesheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets) configuration option.

The order matters here. Font declarations should be at the beginning of the style sheets’ array. Otherwise, there is no guarantee that the font styling will be applied to the PDF file. Refer to the [config.exportPdf.stylesheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets) API documentation for more details.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportPdf: {
            stylesheets: [
                'path/to/fonts.css',
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            // More configuration of the export to PDF feature.
            // ...
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Thanks to this, the editor inherits the font settings and you can be sure that they will be applied in the generated PDF file as well.

Take a look at another example of a `fonts.css` file. Suppose that your website uses the `Source Sans Pro` font as before but this time you want the `Inter` font to be used in the WYSIWYG editor. The file should look like this:

```
/* fonts.css */

/* Import the web font for your website. */
@import url('https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;700&display=swap');
/* Import the web font for your editor. */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');

/* Use the Source Sans Pro web font in your website. */
html, body {
    font-family: "Source Sans Pro", sans-serif;
    /* ... */
}

/* Use the Inter web font in your editor. */
.ck.ck-content.ck-editor__editable {
    font-family: "Inter", sans-serif;
    /* ... */
}

/* ... */

```

Having the file set like this for your website and just re-using it in [config.exportPdf.stylesheets](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-stylesheets) makes the whole setup as simple as possible.

<a id="ckeditor5/latest/features/converters/export-pdf.html--adding-a-watermark-to-the-document">

#### Adding a watermark to the document

Apart from adding a header and a footer, there is also the possibility of adding a watermark to the generated document. This can be achieved by utilizing [config.exportPdf.dataCallback](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html#member-dataCallback).

To do this, you need to get the data that is being sent to the converter first and update it with a watermark markup:

```
exportPdf: {
    // More configuration of the export to PDF.
    // ...
    dataCallback: ( editor ) => {
        return `
            ${ editor.getData() }
            <div class="watermark">Draft document</div>
        `;
    },
    // More configuration of the export to PDF.
    // ...
}

```

Then [update the custom CSS file](#ckeditor5/latest/features/converters/export-pdf.html--re-using-custom-editor-styling) with the proper styles:

```
.watermark {
    font-size: 50px;
    opacity: 0.5;
    color: black;
    position: fixed;
    left: 20%;
    top: 50%;
    transform: rotate(25deg);
    letter-spacing: 10px
}

```

Below you can see a simplified demo with the final result. Click the  toolbar button to generate the document with a watermark.

<a id="ckeditor5/latest/features/converters/export-word.html">source file: "ckeditor5/latest/features/converters/export-word.html"</a>

## Export to Word

The export to Word feature lets you generate a `.docx` file directly from the editor.

<a id="ckeditor5/latest/features/converters/export-word.html--demo">

### Demo

The demo below lets you generate a Word file based on the editor’s content. Edit the document, then click the export to Word toolbar button  to save the content as a Word file.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/converters/export-word.html--how-it-works">

### How it works

The export to Microsoft Word feature collects the HTML generated with the [editor.getData()](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#function-getData) method and the [default editor content styles](#ckeditor5/latest/getting-started/setup/css.html) combined with the styles provided by you in the configuration. It then sends them to the CKEditor Cloud Services HTML to DOCX converter service. The service generates a Word file and returns it to the user’s browser so they can save it in the Word format on their disk.  
You can read more about the converter and the plugin in a [dedicated Feature spotlight blog post](https://ckeditor.com/blog/feature-spotlight-html-to-word-converter/).

You can use the complementary [pagination feature](#ckeditor5/latest/features/pagination/pagination.html) to see where page breaks would be (after exporting your document to Word). However, due to the nature of Word page rendering, the results may be inconsistent (read more about [known issues](#ckeditor5/latest/features/pagination/pagination.html--automatic-page-breaks-in-export-to-word)). You can force the page breaks from pagination in Word by enabling the [auto\_pagination: true](../../api/module%5Fexport-word%5Fexportword-ExportWordConverterOptions.html#member-auto%5Fpagination) configuration option. You can also fine-tune the structure of the output document by using live preview. The pagination feature also shows the page count and lets you navigate between the document pages.

<a id="ckeditor5/latest/features/converters/export-word.html--integration-with-merge-fields-content-placeholders">

### Integration with merge fields (content placeholders)

[Merge fields](#ckeditor5/latest/features/merge-fields.html) are visually distinct placeholder elements you can put into the content to mark places where real values should be inserted. They are perfect for creating document templates and other kinds of personalized content. This allows for automation and creating batch output of personalized `.docx` files. Learn how to configure it in the [Export to Word merge fields](#cs/latest/guides/export-to-word/merge-fields.html) guide.

<a id="ckeditor5/latest/features/converters/export-word.html--before-you-start">

### Before you start

After you select a plan, follow the steps below, as explained in the [Export to Word quick start guide](#cs/latest/guides/export-to-word/quick-start.html):

* [Log into the CKEditor Ecosystem customer dashboard](#cs/latest/guides/export-to-word/quick-start.html--log-in-to-the-customer-portal).
* [Create the token endpoint needed for authorization](#cs/latest/guides/export-to-word/quick-start.html--creating-token-endpoint).
* [Install](#ckeditor5/latest/features/converters/export-word.html--installation) and [configure](#ckeditor5/latest/features/converters/export-word.html--configuration) the CKEditor 5 export to Word plugin.

<a id="ckeditor5/latest/features/converters/export-word.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/converters/export-word.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/converters/export-word.html--default-configuration">

#### Default configuration

This is the default configuration of the Word export feature for CKEditor 5.

```
{
    exportWord: {
        fileName: 'document.docx',
        converterUrl: 'https://docx-converter.cke-cs.com/v2/convert/html-docx',
        stylesheets: [
            './ckeditor5-content.css'
        ],
        converterOptions: {
            document: {
                size: 'A4',
                orientation: 'portrait',
                margin: {
                    top: '1in',
                    bottom: '1in',
                    right: '1in',
                    left: '1in',
                },
                language: 'en' // By default it is set to editor content language.
            },
        },
        dataCallback: ( editor ) => editor.getData( { pagination: true } )
    }
}

```

If you are using the EU cloud region, remember to adjust the endpoint:

```
exportWord: {
    converterUrl: 'https://docx-converter.cke-cs-eu.com/v2/convert/html-docx'
}

```

<a id="ckeditor5/latest/features/converters/export-word.html--stylesheets-option">

#### `stylesheets` option

Use the `stylesheets` option to provide paths (relative or absolute URLs) to all style sheets that should be included during the HTML to DOCX conversion.

The rule of thumb is if you want the export to preserve the styles, always add the style sheets with the content styles of the editor. Their path depends on your application setup, for example:

```
{
    exportWord: {
        stylesheets: [
            './ckeditor5-content.css'
            './styles.css'
        ],
        // ...
    }
}

```

In the snippet above, we assume both style sheets are available via the relative path on the client side. For example, some frameworks allow to place files in the `public` folder.

<a id="ckeditor5/latest/features/converters/export-word.html--plugin-options">

#### Plugin options

For some use cases the default configuration will suffice. As you can see in the example above, you can improve how your Word file will look by adjusting the Word export plugin configuration.

* **[config.exportWord.stylesheets](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-stylesheets)**  
You can set the paths (relative or absolute URLs) to the style sheets that should be included during the HTML to DOCX conversion.
* **[config.exportWord.fileName](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-fileName)**  
Sets the name for the generated Word file (together with the extension). The default name is `document.docx`. You can see it called in the [default configuration](#ckeditor5/latest/features/converters/export-word.html--default-configuration) listing above.  
This option, however, also allows for using a callback to generate a dynamic file name. In the example below, the document’s title will be used as the file name of the generated `.docx` file.  
```  
// Dynamic file name.  
const exportWordConfig = {  
    fileName: () => {  
        const articleTitle = document.querySelector( '#title' );  
        return `${ articleTitle.value }.docx`;  
    }  
}  
```
* **[config.exportWord.converterUrl](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-converterUrl)**  
By default, the Word export feature uses the CKEditor Cloud Services HTML to DOCX converter service to generate the Word files. You can use this option to provide the URL to an on-premises converter. [Contact us](https://ckeditor.com/contact/) if you need this feature.
* **[config.exportWord.tokenUrl](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-tokenUrl)**  
A token URL or a token request function. This field is optional and you should use it when you require a different [tokenUrl](../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) for the export to Word feature. You can skip this option if you use the `cloudServices` configuration to provide the same `tokenUrl`. In most cases you will probably want to provide the token in `cloudServices`, as other plugins like [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) will use this token as well. In this guide, to explicitly show that this value is needed, we leave it inside the `exportWord` configuration.
* **[config.exportWord.converterOptions](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-converterOptions)**  
The plugin allows you to provide a custom [CKEditor Cloud Services HTML to DOCX converter configuration](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-converterOptions), such as paper size, orientation, or watermark. Below, you will find the options listed in a sample configuration:  
```  
        converterOptions: {  
            document: {  
                size: 'A4',  
                margin: {  
                    top: '20mm',  
                    bottom: '20mm',  
                    right: '12mm',  
                    left: '12mm'  
                }  
            },  
            watermark: {  
                source: 'https://placehold.co/600x400/transparent/DDD?text=Watermark',  
                width: '600px',  
                height: '400px',  
                washout: 'true'  
            }  
        }  
```
* **[config.exportWord.dataCallback](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-dataCallback)**  
By default, the plugin uses `editor.getData( { pagination: true } )` to gather the HTML sent to the conversion service. You can use this option to customize the editor’s data.  
When using the [pagination](#ckeditor5/latest/features/pagination/pagination.html) feature, the `pagination:true` option inserts additional markers into the editor’s data. Thanks to that, the HTML to DOCX converter creates a Word document similar to what is displayed in the editor.

<a id="ckeditor5/latest/features/converters/export-word.html--export-to-word-v1">

#### Export to Word V1

**Note:** Export to Word uses the new version of the converter by default, the old one will no longer receive updates. It is highly recommended to migrate to the [latest version](https://docx-converter.cke-cs.com/v2/convert/docs). For more details on migrating from `v1` to `v2` see the [migration guide](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Migrating-from-v1). To use `v1`, you need to specify the version in the `version` property of the configuration, as shown in the snippet below.

```
{
    exportWord: {
        // ...
        version: 1, // by default this is set to 2.
        converterOptions: {
            format: 'A4',
            orientation: 'portrait',
            margin_top: '1in',
            margin_bottom: '1in',
            margin_right: '1in',
            margin_left: '1in'
        },
        // ...
    }
}

```

View V1 headers and footers example 

```
// Let's keep the CSS string as a variable to avoid unnecessary string duplication.
const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    header: [
        // Header template for all headers (without the `type` property).
        { html: '<p class="styled">Default header content</p>', css: templateCSS },
        // Header template only for the first page of the document.
        { html: '<p class="styled">First document page header content</p>', css: templateCSS, type: 'first' },
        // Header template for every even page of the document.
        { html: '<p class="styled">Every even page header content</p>', css: templateCSS, type: 'even' },
        // Header template for every odd page of the document.
        { html: '<p class="styled">Every odd page header content</p>', css: templateCSS, type: 'odd' }
    ],
    footer: [
        // Footer template for all footers (without the `type` property).
        { html: '<p class="styled">Default footer content</p>', css: templateCSS },
        // Footer template only for the first page of the document.
        { html: '<p class="styled">First document page footer content</p>', css: templateCSS, type: 'first' },
        // Footer template for every even page of the document.
        { html: '<p class="styled">Every even page footer content</p>', css: templateCSS, type: 'even' },
        // Footer template for every odd page of the document.
        { html: '<p class="styled">Every odd page footer content</p>', css: templateCSS, type: 'odd' }
    ],
}

```

<a id="ckeditor5/latest/features/converters/export-word.html--html-to-word-converter-features">

### HTML to Word converter features

<a id="ckeditor5/latest/features/converters/export-word.html--styling-a-document">

#### Styling a document

By default, the [export to Word](../../api/module%5Fexport-word%5Fexportword-ExportWord.html) plugin takes editor content styles and sends them to the CKEditor Cloud Services HTML to DOCX Converter. You can also add custom styles by providing the paths to the external CSS files.

```
// More editor's configuration.
// ...
exportWord: {
    fileName: 'document.docx',
    converterUrl: 'https://docx-converter.cke-cs.com/v2/convert/html-docx',
    stylesheets: [
        'path/to/editor-styles.css',
        'path/to/my-styles.css'
    ],
    // More configuration of the export to Word feature.
    // ...
}
// More editor's configuration.
// ...

```

<a id="ckeditor5/latest/features/converters/export-word.html--supported-css-properties">

##### Supported CSS properties

The HTML to DOCX Converter supports proper CSS inheritance with a set of whitelisted properties. You can use them to style the document content.

You can apply CSS properties like:

* `color`
* `background-color`
* `font-size`
* `font-family`
* `text-align`

to the following elements: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `span`, `td`, `th`, `strong`, `i`, `u`, `s`, `sub`, `sup`, `mark`.

You can also position images using the `float` CSS property, supporting `left`, `right`, and `none` values.

<a id="ckeditor5/latest/features/converters/export-word.html--setting-the-page-format">

#### Setting the page format

Consistency is an important factor. To make sure that the editor content and the generated Word file look the same, you need to match their format settings. You can change your existing style sheet or use a new one, for example, `format.css`. By default, the CKEditor Cloud Services HTML to DOCX converter is set to A4 format, but you may change this setting in your configuration.

Assuming that you want to create a document in the US Letter format, with the standard margins (`19mm` for each side), here is the example code you can use:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportWord: {
            stylesheets: [
                'path/to/editor-styles.css',
                'path/to/my-styles.css'
            ],
            fileName: 'my-document.docx',
            converterOptions: {
                document: {
                    size: 'Letter',
                    // Document format settings with proper margins.
                    margin: {
                        top: '19mm',
                        bottom: '19mm',
                        right: '19mm',
                        left: '19mm'
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Now set the corresponding editor styles:

```
/* format.css */

/* Styles for the editable. */
.ck.ck-content.ck-editor__editable {
    /* US Letter size. */
    width: 215.9mm;
    /* Padding is your document's margin. */
    padding: 19mm;
    /* You don't want to change the size of the editor by applying the new padding values. */
    box-sizing: border-box;
    /* ... */
}

```

With these settings, the content in the generated Word file should have the same US Letter format layout as it has in the editor.

<a id="ckeditor5/latest/features/converters/export-word.html--header-and-footer">

#### Header and footer

The converter lets you set the document’s header and footer similarly to Microsoft Word or Google Docs.

```
const templateCSS = '.styled { color: #4b22aa; text-align: center; }'

const converterOptions = {
    headers: {
        // Header template for all headers.
        default : {
            html: '<p class="styled">Default header content</p>',
            css: templateCSS
        },
        // Header template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page header content</p>',
            css: templateCSS
        },
        // Header template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page header content</p>',
            css: templateCSS
        },
        // Header template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page header content</p>',
            css: templateCSS
        }
    },
    footers: {
        // Footer template for all footers.
        default: {
            html: '<p class="styled">Default footer content</p>',
            css: templateCSS
        },
        // Footer template only for the first page of the document.
        first: {
            html: '<p class="styled">First document page footer content</p>',
            css: templateCSS
        },
        // Footer template for every even page of the document.
        even: {
            html: '<p class="styled">Every even page footer content</p>',
            css: templateCSS
        },
        // Footer template for every odd page of the document.
        odd: {
            html: '<p class="styled">Every odd page footer content</p>',
            css: templateCSS
        }
    },
}

```

There are only the `headers` and `footers` objects which contain other objects where the key is a `type` of your header/footer.

Regarding CSS, you can style the `headers` and `footers` using the same [supported properties](#ckeditor5/latest/features/converters/export-word.html--supported-css-properties) as used for styling the whole document.

For more details, refer to the [CKEditor Cloud Services HTML to DOCX converter’s documentation](https://docx-converter.cke-cs.com/docs#section/Options).

As you can see, the `headers` and `footers` options take an array of objects that define templates for the particular type of page. If you want to have consistent templates no matter the page, you can define only the `default` `headers/footers` template (**Note:** This setting misses the `type` property on purpose).

If you import headers and footers from a Word document and want to preserve and reapply them when exporting, see the [preserving headers and footers](#ckeditor5/latest/features/converters/import-word/import-word.html--preserving-headers-and-footers) section in the [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) guide.

<a id="ckeditor5/latest/features/converters/export-word.html--setting-the-base-url">

#### Setting the base URL

To enable proper resolution of relative URLs for images and links, you need to pass the `base_url` option:

```
const conversionOptions = {
    base_url: 'https://ckeditor.com'
};

```

For an editor’s content like the one below:

```
<p><a href="/">Our company homepage</a></p>
<p><img src="/logo.svg" alt="Our logo"></p>

```

this option will result in resolving these URLs into their absolute forms:

* `/` will become `https://ckeditor.com`,
* `/logo.svg` will become `https://ckeditor.com/logo.svg`.

<a id="ckeditor5/latest/features/converters/export-word.html--adding-a-watermark">

#### Adding a watermark

The Export to Word converter allows for easy adding a graphic watermark via the [converterOptions](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html#member-converterOptions) configuration setting.

The watermark configuration is represented as an object containing 4 properties:

* `source`: A source of the image used for the watermark.
* `width`: A string value representing the width of the watermark.
* `height`: A string value representing the height of the watermark.
* `washout`: Determines whether the washout effect should be applied. Optional - the default value is `false`.

```
    converterOptions: {
        watermark: {
            source: 'https://placehold.co/600x400/EEE/31343C',
            width: '600px',
            height: '400px',
            washout: 'true'
        }
    }

```

<a id="ckeditor5/latest/features/converters/export-word.html--comments-and-suggestions">

#### Comments and suggestions

When your editor has [collaboration features](https://ckeditor.com/collaboration/) (like comments and track changes) enabled, the [export to Word](../../api/module%5Fexport-word%5Fexportword-ExportWord.html) feature will take care of setting the configuration needed by the CKEditor Cloud Services HTML to DOCX converter. But if for some reason you need to pass your own data, you can do this via the [REST API converter options](https://docx-converter.cke-cs.com/docs#section/Options).

<a id="ckeditor5/latest/features/converters/export-word.html--other">

#### Other

* By default, the generated Word file is encoded with **`UTF-8`**.

<a id="ckeditor5/latest/features/converters/export-word.html--known-issues">

### Known issues

Not all CKEditor 5 plugins and features are compatible with export to Word at the moment. Feel free to [contact us](https://ckeditor.com/contact/) if you are interested in any of these features specifically. Here is a list of known issues:

<a id="ckeditor5/latest/features/converters/export-word.html--automatic-page-breaks-with-the-pagination-feature">

#### Automatic page breaks with the pagination feature

Browser engines and Microsoft Word differ significantly. Because of that, the automatic prediction of page breaks provided by the [pagination feature](#ckeditor5/latest/features/pagination/pagination.html) in [Export to Word](#ckeditor5/latest/features/converters/export-word.html) is problematic and error-prone. We recommend reviewing your document’s structure during the exporting and manually applying the page breaks to maintain the preferred structure. If you still want to enforce the page breaks, set the `auto_pagination: true` option in the Export to Word configuration. You can also use [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html), where predicting page breaks is more straightforward and works more consistently.

<a id="ckeditor5/latest/features/converters/export-word.html--unsupported-plugins">

#### Unsupported plugins

* [Media embed](#ckeditor5/latest/features/media-embed.html) – Embedded media will not be included in the exported document.
* [MathType](#ckeditor5/latest/features/math-equations.html) – Supported partially. The plugin parses the data but not the formatting, losing some of the math operators and not reproducing a usable equation in the effecting file.

<a id="ckeditor5/latest/features/converters/export-word.html--unsupported-features">

#### Unsupported features

* Inline and block formatting [suggestions](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Such suggestions are not included in the exported document.
* [Comments](#ckeditor5/latest/features/collaboration/comments/comments.html) applied to whole widgets (like tables) – Such comments are not included in the exported document.

<a id="ckeditor5/latest/features/converters/export-word.html--related-features">

### Related features

* The complementary [pagination feature](#ckeditor5/latest/features/pagination/pagination.html) provides live preview of the document’s page breaks, ensuring the output document looks correct.
* If you would like to export your content to a portable, universal format, using the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature will allow you to generate PDF files out of your editor-created content.

<a id="ckeditor5/latest/features/converters/export-word.html--common-api">

### Common API

The [ExportWord](../../api/module%5Fexport-word%5Fexportword-ExportWord.html) plugin registers:

* The `'exportWord'` button.
* The `'exportWord'` command implemented by [ExportWordCommand](../../api/module%5Fexport-word%5Fexportwordcommand-ExportWordCommand.html).  
You can execute the command using the [editor.execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method. However, if you want to use the command directly (not via the toolbar button), you need to specify the [the options](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html) or gather them from the configuration. Otherwise, the command will not execute properly.  
The example code to use the command directly should look like this:  
```  
// Start generating a Word file based on the editor content and the plugin configuration.  
const config = editor.config.get( 'exportWord' );  
editor.execute( 'exportWord', config );  
```

<a id="ckeditor5/latest/features/converters/export-word.html--rest-api">

### REST API

The HTML to DOCX converter provides an API for converting HTML documents to Microsoft Word `.docx` files. Read the [REST API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word) to find out how to employ it in your implementation.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html">source file: "ckeditor5/latest/features/converters/import-word/features-comparison.html"</a>

## Import from Word vs paste from Office comparison

In addition to import from Word, there is a simpler [paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) plugin that lets you paste content from Microsoft Word while maintaining its original structure and formatting. However, these two solutions differ in many ways.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--paste-from-office">

### Paste from Office

The [paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) and [paste from Office enhanced](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) features allow you to paste content from Microsoft Word into your CKEditor 5 WYSIWYG editor and maintain the original structure and formatting. After creating a document in Microsoft Word you can copy it to CKEditor 5 and retain basic text styling, heading levels, links, lists, tables, and images – as long as these features are supported by the editor itself.

* Suitable for small documents and for use cases in which only parts of the document are selected and copied.
* Relies on OS Clipboard HTML, which limits the number of supported features.
* Preserves the original DOCX formatting that was selected and copied by hand.
* Simple, intuitive, but cannot be used to automate the migration process of many Word documents via the REST API.

This operation is fast and easy, but can only be done manually.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--import-from-word">

### Import from Word

The import from Word service can be automated and does not require the presence of the WYSIWYG editor, nor human supervision to convert files. Compared to paste from Office, import can work with any [content formatting](#cs/latest/guides/import-from-word/content-formatting.html) and is not limited by features supported by the editor.

* Allows for converting large documents into HTML that can be easily imported to CKEditor 5 and other tools.
* Operates directly on XML, which includes more information about the document and Word instance settings.
* Available as a CKEditor 5 plugin and as a REST API for a direct server-to-server conversion.
* Available both as a SaaS service and as an on-premises solution.
* Suitable for migration of the whole database of Word documents to HTML via a REST API service.
* Perfect solution for more advanced documents that need to be edited or displayed in the browser.
* Supports collaboration features like track changes and comments out of the box.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--features-comparison">

### Features comparison

The following tables compare the features of the paste from Office and paste from Office enhanced CKEditor 5 plugin and the import from Word feature. For a more detailed import from Word features overview, refer to the [content formatting](#cs/latest/guides/import-from-word/content-formatting.html) guide.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--collaboration-features">

#### Collaboration features

| Feature name                    | Paste | Enhanced | Import |
| ------------------------------- | ----- | -------- | ------ |
| Comments                        | ❌     | ❌        | ✅      |
| Comments archive                | ❌     | ❌        | ✅      |
| Comments - images               | ❌     | ❌        | ✅      |
| Comments - table cells          | ❌     | ❌        | ✅      |
| Track changes - text insertion  | ❌     | ❌        | ✅      |
| Track changes - text deletion   | ❌     | ❌        | ✅      |
| Track changes - move text       | ❌     | ❌        | ✅      |
| Track changes - images          | ❌     | ❌        | ✅      |
| Track changes - tables          | ❌     | ❌        | ⚠️     |
| Track changes - table text      | ❌     | ❌        | ✅      |
| Track changes - table rows      | ❌     | ❌        | ⚠️     |
| Track changes - table cells     | ❌     | ❌        | ⚠️     |
| Track changes - lists           | ❌     | ❌        | ⚠️     |
| Track changes - list text       | ❌     | ❌        | ✅      |
| Track changes - list items      | ❌     | ❌        | ⚠️     |
| Track changes - text formatting | ❌     | ❌        | ⚠️     |

* ⚠️ Import: Track changes for unsupported features will preserve the original content of the author’s suggestion. However, they will not be recognized as proper track changes suggestions. As an example, if a user adds a table using track changes, the table will be output in HTML, but it will not be marked as a suggestion. That limitation is going to be fixed soon, with upcoming import From Word releases.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--inline-formatting">

#### Inline formatting

| Feature name     | Paste | Enhanced | Import |
| ---------------- | ----- | -------- | ------ |
| Font color       | ✅     | ✅        | ✅      |
| Font background  | ✅     | ✅        | ✅      |
| Font size        | ✅     | ✅        | ✅      |
| Font family      | ✅     | ✅        | ✅      |
| Bold             | ✅     | ✅        | ✅      |
| Italics          | ✅     | ✅        | ✅      |
| Underline        | ✅     | ✅        | ✅      |
| Underline custom | ❌     | ⚠️       | ✅      |
| Strike-through   | ✅     | ✅        | ✅      |
| Subscript        | ✅     | ✅        | ✅      |
| Superscript      | ✅     | ✅        | ✅      |
| Link             | ✅     | ✅        | ✅      |
| Soft line break  | ✅     | ✅        | ✅      |
| Small caps       | ❌     | ✅        | ✅      |
| All caps         | ❌     | ✅        | ✅      |
| Letter spacing   | ⚠️    | ✅        | ✅      |
| Font stretching  | ❌     | ✅        | ✅      |
| Hidden text      | ⚠️    | ⚠️       | ✅      |

* ⚠️ Paste: Letter spacing and hidden text are only supported with the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature enabled.
* ⚠️ Paste enhanced: Advanced underline is pasted as regular underline.
* ⚠️ Paste enhanced: Hidden text is only supported with the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature enabled.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--paragraphs">

#### Paragraphs

| Feature name           | Paste | Enhanced | Import |
| ---------------------- | ----- | -------- | ------ |
| Text alignment         | ✅     | ✅        | ✅      |
| Indentation            | ✅     | ✅        | ✅      |
| First line indentation | ⚠️    | ⚠️       | ✅      |
| Hanging indentation    | ⚠️    | ⚠️       | ✅      |
| Line height            | ⚠️    | ⚠️       | ✅      |
| Paragraph spacing      | ⚠️    | ⚠️       | ✅      |
| Paragraph borders      | ⚠️    | ⚠️       | ✅      |
| Background color       | ⚠️    | ⚠️       | ✅      |

* ⚠️ First line indentation, hanging indentation, line height, paragraph spacing, and paragraph borders are only supported with the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature enabled.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--headings">

#### Headings

| Feature name                       | Paste | Enhanced | Import |
| ---------------------------------- | ----- | -------- | ------ |
| Built-in heading styles            | ✅     | ✅        | ✅      |
| Preservation of heading formatting | ❌     | ✅        | ✅      |
| Custom outline level               | ❌     | ✅        | ✅      |

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--lists">

#### Lists

| Feature name                           | Paste | Enhanced | Import |
| -------------------------------------- | ----- | -------- | ------ |
| Ordered lists                          | ✅     | ✅        | ✅      |
| Unordered lists                        | ✅     | ✅        | ✅      |
| Custom list markers                    | ❌     | ️❌       | ❌      |
| Ordered list language-specific markers | ❌     | ❌        | ✅      |
| Custom start number                    | ✅     | ✅        | ✅      |
| Different start number in the middle   | ❌     | ❌        | ✅      |
| Multi-level list                       | ❌     | ❌        | ⚠️     |

* ⚠️ Import: Support for multi-level lists with X level of tabulation shifting is now available. Please be aware that marker continuation from previous levels (for example, 2.1, 2.2) is not supported for now.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--tables">

#### Tables

| Feature name                | Paste | Enhanced | Import |
| --------------------------- | ----- | -------- | ------ |
| Table width                 | ✅     | ✅        | ✅      |
| Cell/column width           | ✅     | ✅        | ✅      |
| Cell/row height             | ✅     | ✅        | ✅      |
| Cell merging                | ✅     | ✅        | ✅      |
| Cell padding                | ✅     | ✅        | ✅      |
| Cell spacing                | ✅     | ✅        | ✅      |
| Cell’s horizontal alignment | ✅     | ✅        | ✅      |
| Cell’s vertical alignment   | ✅     | ✅        | ✅      |
| Table background color      | ✅     | ✅        | ✅      |
| Cell background color       | ✅     | ✅        | ✅      |
| Table border style          | ✅     | ✅        | ✅      |
| Table border color          | ✅     | ✅        | ✅      |
| Cell border style           | ✅     | ✅        | ✅      |
| Cell border color           | ✅     | ✅        | ✅      |
| Table header                | ✅     | ✅        | ✅      |
| Nested tables               | ✅     | ✅        | ✅      |
| Table alignment/floating    | ✅     | ✅        | ✅      |
| Table caption               | ⚠️    | ⚠️       | ⚠️     |

* ⚠️ Table caption is converted to a styled (only import) paragraph.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--images-update-after-release">

#### Images 

| Feature name                 | Paste | Enhanced | Import |
| ---------------------------- | ----- | -------- | ------ |
| Embedded images              | ✅     | ✅        | ✅      |
| External images              | ✅     | ✅        | ✅      |
| Image link                   | ✅     | ✅        | ✅      |
| Image alternative text       | ✅     | ✅        | ✅      |
| Image height                 | ✅     | ✅        | ✅      |
| Image width                  | ✅     | ✅        | ✅      |
| Image alignment              | ✅     | ✅        | ✅      |
| Absolutely positioned images | ⚠️    | ⚠️       | ⚠️     |
| Image caption                | ⚠️    | ⚠️       | ⚠️     |

* ⚠️ Absolutely positioned images are retained, but their original position is lost.
* ⚠️ Image caption is converted to a styled (import only) paragraph.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--page-breaks">

#### Page breaks

| Feature name            | Paste | Enhanced | Import |
| ----------------------- | ----- | -------- | ------ |
| Normal page break       | ✅     | ✅        | ✅      |
| Page break before style | ❌     | ❌        | ✅      |

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--horizontal-lines">

#### Horizontal lines

| Feature name    | Paste | Enhanced | Import |
| --------------- | ----- | -------- | ------ |
| Horizontal line | ✅     | ✅        | ✅      |

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--word-styles">

#### Word styles

| Feature name     | Paste | Enhanced | Import |
| ---------------- | ----- | -------- | ------ |
| Built-in styles  | ❌     | ⚠️       | ✅      |
| Format styles    | ❌     | ⚠️       | ✅      |
| Font styles      | ❌     | ⚠️       | ✅      |
| Paragraph styles | ❌     | ⚠️       | ✅      |
| Border styles    | ❌     | ⚠️       | ✅      |
| Numbering styles | ✅     | ✅        | ✅      |

* ⚠️ Paste enhanced: Styles are only supported with the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature enabled.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--default-styles">

#### Default styles

Default styles require enabling the `config.default_styles` configuration option, both for the CKEditor 5 import from Word plugin and the REST API.

| Feature name     | Paste | Enhanced | Import |
| ---------------- | ----- | -------- | ------ |
| Format styles    | ⚠️    | ✅        | ✅      |
| Font styles      | ⚠️    | ✅        | ✅      |
| Paragraph styles | ⚠️    | ✅        | ✅      |

* ⚠️ Paste: Default document styles are partially supported, but cannot be disabled or enabled on purpose.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--sections">

#### Sections

| Feature name             | Paste | Enhanced | Import |
| ------------------------ | ----- | -------- | ------ |
| Document margins         | ❌     | ✅        | ✅      |
| Document size            | ❌     | ✅        | ✅      |
| Multi-sectioned document | ❌     | ❌        | ❌      |
| Section columns          | ❌     | ❌        | ❌      |
| Headers and footers      | ❌     | ❌        | ❌      |

* ⚠️ Import: Multi-sectioned document and section columns are currently not supported.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--complex-objects">

#### Complex objects

| Feature name      | Paste | Enhanced | Import |
| ----------------- | ----- | -------- | ------ |
| Table of contents | ⚠️    | ✅        | ✅      |
| Form objects      | ⚠️    | ⚠️       | ⚠️     |

* ⚠️ Paste: Only the table of contents text is preserved, but the structure and styling are lost.
* ⚠️ Form objects: Only text and styling are retained.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--technical-details">

### Technical details

To better understand the differences between these two products, it is worth learning how both features work on a technical level. In paste from Office, the editor uses the operating system’s clipboard, which is fed with Microsoft Word content in HTML upon copying it from the document. That HTML is delivered by the Word application itself and includes the essential formatting of the document. When the user pastes something from a Word document, CKEditor 5 cleans that HTML up and makes it semantically correct, so it can be consumed by the editor. However, that operation has its limitations, as CKEditor 5 is only able to understand as much content as it gets from the clipboard and depends entirely on the clipboard implementation of the Microsoft Word application.

The import from Word feature does not have this limitation. As it has direct access to the document, it can retrieve as much information from the document as Word. Therefore, it is possible to support things like collaboration features, document settings, and others, which would not be available when operating on clipboard content only. We are no longer limited by the Microsoft Word application and thanks to that, import from Word produces a more advanced HTML than Paste from Word.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--list-of-css-properties-that-require-ghs">

### List of CSS properties that require GHS

This is a list of all CSS properties that are properly converted by the [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature, but will not work by default in CKEditor 5 and require the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) (GHS) feature.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--paragraphs-2">

#### Paragraphs

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements">

##### HTML elements:

* `p`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties">

##### CSS properties:

* `background-color`
* `line-height`
* `border-top`
* `border-bottom`
* `border-left`
* `border-right`
* `margin-top`
* `margin-bottom`
* `text-indent`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--headings-2">

#### Headings

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-2">

##### HTML elements

* `h1`
* `h2`
* `h3`
* `h4`
* `h5`
* `h6`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-2">

##### CSS properties:

* `font-weight`
* `font-size`

Headings also require all CSS properties that paragraphs do.

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--lists-2">

#### Lists

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-3">

##### HTML elements:

* `ul`
* `ol`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-3">

##### CSS properties:

* `list-style-type`
* `margin-top`
* `margin-bottom`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--list-items">

#### List items

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-4">

##### HTML elements:

* `li`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-4">

##### CSS properties:

* `list-style-type`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--spans">

#### Spans

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-5">

##### HTML elements:

* `span`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-5">

##### CSS properties:

* `letter-spacing`
* `text-transform`
* `font-variant-caps`
* `font-stretch`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--underlines">

#### Underlines

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-6">

##### HTML elements:

* `u`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-6">

##### CSS properties:

* `text-decoration-line`
* `text-decoration-style`
* `text-decoration-thickness`
* `text-decoration-color`
* `text-decoration-skip-ink`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--images">

#### Images

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-7">

##### HTML elements:

* `img`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-7">

##### CSS properties:

* `position`
* `display`
* `float`
* `margin-top`
* `margin-left`
* `margin-right`
* `transform`
* `z-index`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--figures">

#### Figures

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-8">

##### HTML elements:

* `figure`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-8">

##### CSS properties:

* `margin-top`
* `margin-bottom`
* `margin-left`
* `margin-right`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--tables-2">

#### Tables

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-9">

##### HTML elements:

* `table`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-9">

##### CSS properties:

* `border-collapse`
* `border-spacing`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--table-cells">

#### Table cells

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-10">

##### HTML elements:

* `td`
* `th`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-10">

##### CSS properties:

* `vertical-align`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--table-header-cells">

#### Table header cells

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--html-elements-11">

##### HTML elements:

* `th`

<a id="ckeditor5/latest/features/converters/import-word/features-comparison.html--css-properties-11">

##### CSS properties:

* `font-weight`
* `text-align`

<a id="ckeditor5/latest/features/converters/import-word/import-word.html">source file: "ckeditor5/latest/features/converters/import-word/import-word.html"</a>

## Import from Word

The import from Word feature lets you import `.docx` (Word document) or `.dotx` (Word template) files into the editor. The process preserves formatting and rich media as well as [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [tracked changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) (if these features are enabled).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--demo">

### Demo

The demo below lets you import a Word file into the editor. To test the feature, download the [sample Word document](../../../assets/pd%5Fpolicy.docx). Use the import from Word toolbar button  and select the downloaded file. The file’s content will appear in the editor.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--additional-feature-information">

### Additional feature information

The import from Word feature sends the selected Word file to the CKEditor Cloud Services DOCX to HTML converter service. The service returns HTML code generated from the uploaded file and then inserts it into the editor content in place of the document selection.

Even though CKEditor 5 offers a dedicated [pagination plugin](#ckeditor5/latest/features/pagination/pagination.html), it cannot be used to reflect the original page division in content imported from Word. This is an export-only feature.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--importing-styles">

### Importing styles

CKEditor 5 supports two strategies for importing styles from Word:

1. Using styles defined in CKEditor 5.
2. Using styles defined in Word.

The decision as to which approach to use is strongly related to your use case. The ability to choose whether to retain or to drop native Word styles gives you great flexibility. It also allows you to tailor the service to your specific needs.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--using-styles-defined-in-ckeditor">

#### Using styles defined in CKEditor

The import from Word feature is pre-configured to preserve styles defined in the CKEditor 5’s implementation or applied directly by the end-user. This means that it will retain basic text styling (like bold or italics), headings, images, tables, and the overall document structure. At the same time, it will allow the editor to apply styles used by CKEditor 5 to the imported content for more general formatting, like font family, font size, paragraph spacing, etc. if not set.

This way you import the file content into the editor and it does not differ visually from the already existing content. This is useful when the formatting needs to follow corporate guidelines or a brand book. With that approach, import keeps semantically close formatting to the existing content.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--using-styles-defined-in-microsoft-word">

#### Using styles defined in Microsoft Word

Word allows you to change the default formatting of documents to style them in a specific way. You can apply the same style to the entire Word document without needing to do it manually. For example, you can open the Format menu, choose the Font option, and then change some formatting, such as font size and font family. The behavior of that Word feature highly impacts how the document will be styled after the conversion. Therefore, instead of always applying the default styles, the converter can enable importing the entire Word document styling. In this approach, the Word default content formatting set for the whole document is all included in the import and preserved as much as possible (within the support of CKEditor 5 feature plugins). Word [applies styles in a specific way](#cs/latest/guides/import-from-word/styles.html--default-styles), and the user may choose to retain these.

To make the converter work this way, set the [FormattingOptions](../../../api/module%5Fimport-word%5Fimportword-ImportWordFormattingOptions.html). This approach is most useful when users want to edit a Word document directly in their browser and need cross-platform interoperability. You can call it the “complete Word editing experience.” However, an integrator can still choose which styles to preserve by configuring CKEditor 5 appropriately.

A sample configuration for this option may look similar to this one:

```
importWord: {
    formatting: {

        // Keep only very minimal styling in comments:
        comments: 'basic',

        // Do not include Word default document styles (e.g. default font / size):
        defaults: 'none',

        // Include resets so that HTML heading tags reflect Word heading defaults
        resets: 'inline',

        // Preserve Word-defined styles inline:
        styles: 'inline'
    }
}

```

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--paste-from-office-vs-import-from-word">

### Paste from Office vs import from Word

The [paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) feature allows you to paste content from Microsoft Word into your CKEditor 5 WYSIWYG editor and maintain the original structure and formatting. After creating a document in Microsoft Word, you can copy it to CKEditor 5 and retain basic text styling, heading levels, links, lists, tables, and images if these features are supported by the installed CKEditor 5 plugins. For example, if font colors are not explicitly turned on in the editor instance, they will be dropped. This operation is fast and easy, but can only be done manually.

[Import from Word](#cs/latest/guides/import-from-word/overview.html), however, is much more advanced. First of all, you can automate it and it does not need the presence of CKEditor 5 editor or human supervision to convert files. You can feed the files into the service and convert them automatically, as part of a larger process.

While the paste from Office feature can only retain the formatting supported by the editor instance, this limitation does not concern the import from Word service. You can read more about the differences and specific supported features in the [dedicated comparison guide](#ckeditor5/latest/features/converters/import-word/features-comparison.html).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--automatic-content-filtering">

### Automatic content filtering

Due to the CKEditor 5 [custom data model](#ckeditor5/latest/framework/index.html), the editor will only preserve content handled by its plugins. This guarantees that the output provided by CKEditor 5 will be clean and semantic.

However, this also means that you may need to enable some additional plugins in your rich-text editor to prevent stripping content or formatting (for example, the [font family and font size](#ckeditor5/latest/features/font.html) features to handle font formatting).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--base64-images-and-content-security-policy">

### `base64` images and Content Security Policy

If you use the import from Word plugin without custom uploaders, Content Security Policy (CSP) may prevent `base64` images from being imported due to security concerns. This will result in an error in the console like this one:

```
Refused to connect to `data:image/jpeg:base64,/xxxxx utills.js:43 xxxxx` because it violates the documents Content Security Policy.

```

In such a case, you should try using a ready-made upload solution like [CKBox](#ckeditor5/latest/features/file-management/ckbox.html). You can also consider changing the CSP directive.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--comments-and-tracked-changes">

### Comments and tracked changes

The import from Word feature supports Word files with comments and tracked changes. They will be imported as long as your CKEditor 5 preset includes the [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) features.

All comments and suggestions imported from a Word file will use the same author’s name as in the Word file. They will also include a special label informing that a given item comes from an external source.

Read more about the integration between the import from Word and the comments feature in the [Comments walkthrough](#ckeditor5/latest/features/collaboration/comments/comments-walkthrough.html--import-from-word) guide.

If your CKEditor 5 preset does not include the track changes feature, the content will be imported as if all tracked changes were accepted (same as “No Markup” displayed mode).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--merge-fields-content-placeholders">

### Merge fields (content placeholders)

The import from Word feature will recognize Word document merge fields and will seamlessly convert them to the [editor merge fields](#ckeditor5/latest/features/merge-fields.html).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--before-you-start">

### Before you start

You can try the import from Word feature in preview mode without a valid license. It will import a part of the document, and replace the rest of the content with a “lorem ipsum” text placeholder.

After you purchase a license, follow the steps below, as explained in the [Import from Word quick start guide](#cs/latest/guides/import-from-word/quick-start.html):

* [Log into the CKEditor Ecosystem customer dashboard](#cs/latest/guides/import-from-word/quick-start.html--log-in-to-the-customer-portal).
* [Create the token endpoint needed for authorization](#cs/latest/guides/import-from-word/quick-start.html--creating-token-endpoint).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--configuration">

### Configuration

You can configure the feature via the [config.importWord](../../../api/module%5Fimport-word%5Fimportword-ImportWordConfig.html) object.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--providing-the-token-url">

#### Providing the token URL

The import from Word feature requires the token endpoint URL configured in the [config.importWord.tokenUrl](../../../api/module%5Fimport-word%5Fimportword-ImportWordConfig.html#member-tokenUrl) key. If not explicitly provided, the token URL from [config.cloudServices.tokenUrl](../../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) is used instead. If both are provided, the token URL defined in `config.importWord.tokenUrl` takes precedence over the `config.cloudServices.tokenUrl`.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        importWord: {
            tokenUrl: 'https://example.com/cs-token-endpoint'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--configuring-the-converter-service-url">

#### Configuring the converter service URL

Below is the default configuration of the Import from Word feature for CKEditor 5 with Cloud Services.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        importWord: {
            converterUrl: 'https://docx-converter.cke-cs.com/v2/convert/docx-html'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If you are using the EU cloud region, remember to adjust the endpoint:

```
importWord: {
    converterUrl: 'https://docx-converter.cke-cs-eu.com/v2/convert/docx-html'
}

```

If the service is hosted in your own environment, you should configure the converter service URL via the [config.importWord.converterUrl](../../../api/module%5Fimport-word%5Fimportword-ImportWordConfig.html#member-converterUrl) option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        importWord: {
            converterUrl: 'https://example.com/converter'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--default-styles">

#### Default styles

By default, the converter service will convert styles explicitly applied to the content. You can change this behavior by passing the [config.importWord.formatting](../../../api/module%5Fimport-word%5Fimportword-ImportWordConfig.html#member-formatting) object:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        importWord: {
            formatting: {
                resets: 'none',
                defaults: 'none',
                styles: 'inline'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--comments-styles">

#### Comments styles

If the imported document contains comments, only their basic styles will be kept by default. However, you can change this behavior by passing the [config.importWord.formatting.comments](../../../api/module%5Fimport-word%5Fimportword-ImportWordFormattingOptions.html#member-comments) option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        importWord: {
            formatting: {
                comments: 'none'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This configuration option can take the following values:

* `'basic'` – Only basic styles are kept (bold, italic, underline, strikethrough and links).
* `'none'` – Comment text is imported without any styling.
* `'full'` – All styles are preserved (not recommended).

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--preserving-headers-and-footers">

### Preserving headers and footers

While CKEditor 5 currently focuses on editing the document body, you can preserve headers and footers during the import process to ensure a lossless round-trip (Import Word → CKEditor 5 → Export Word).

The converter service returns header and footer data in the response. You can intercept this data using the [dataInsert](../../../api/module%5Fimport-word%5Fimportwordcommand-ImportWordCommand.html#event-dataInsert) event, store it (for example, in dedicated model roots), and then reapply it when exporting the document using the [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature.

The following example plugin demonstrates how to:

1. Capture headers and footers from the import response.
2. Store them in separate model roots. Note the use of `undoStepBatch` to ensure that the user can undo the entire import operation in a single step.
3. Inject the stored data back into the configuration when the `exportWord` command is executed.

```
import { Plugin } from 'ckeditor5';
import { ImportWordEditing } from 'ckeditor5-premium-features';

class StoreHeadersAndFootersPlugin extends Plugin {
    static get pluginName() {
        return 'StoreHeadersAndFootersPlugin';
    }

    static get requires() {
        return [ ImportWordEditing ];
    }

    init() {
        const importCommand = this.editor.commands.get( 'importWord' );

        this.listenTo( importCommand, 'dataInsert', ( _, { headers, footers, undoStepBatch } ) => {
            undoStepBatch ??= importCommand._undoStepBatch;

            this._processSection( undoStepBatch, 'header', headers ?? {} );
            this._processSection( undoStepBatch, 'footer', footers ?? {} );
        } );
    }

    afterInit() {
        const exportCommand = this.editor.commands.get( 'exportWord' );

        if ( exportCommand ) {
            this.listenTo( exportCommand, 'execute', ( _, [ data ] ) => {
                data.dataCallback = () => this.editor.getData({ rootName: 'content' });
                data.converterOptions = {
                    ...data.converterOptions ?? {},
                    headers: this._getExportDataForSection( 'header' ),
                    footers: this._getExportDataForSection( 'footer' )
                };
            }, { priority: 'high' } );
        }
    }

    /**
     * Iterates over section variants (default, first, odd, even) and updates roots.
     */
    _processSection( batchType, type, definitions ) {
        const { model, data } = this.editor;

        for ( const [ variant, content ] of Object.entries( definitions ) ) {
            const rootName = `${ type }:${ variant }`;

            model.enqueueChange( batchType, writer => {
                if ( !model.document.getRoot( rootName )?.isAttached() ) {
                    writer.addRoot( rootName, '$root' );
                }
            } );

            data.set( { [ rootName ]: content.html }, {
                suppressErrorInCollaboration: true,
                batchType,
            } );
        }
    }

    /**
     * Gathers export data for headers or footers.
     */
    _getExportDataForSection( type ) {
        const exportData = Object.create( null );

        for ( const variant of [ 'default', 'first', 'odd', 'even' ] ) {
            const rootName = `${ type }:${ variant }`;
            const root = this.editor.model.document.getRoot( rootName );

            if ( root?.isAttached() ) {
                const html = this.editor.getData( { rootName } )?.trim();

                if ( html ) {
                    exportData[ variant ] = {
                        html
                    };
                }
            }
        }

        return exportData;
    }
}

```

For more details, visit the [ckeditor5-collaboration-samples](https://github.com/ckeditor/ckeditor5-collaboration-samples/) repository, which contains a complete example of how to implement this feature.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--making-headers-and-footers-editable">

#### Making headers and footers editable

Since the implementation above stores headers and footers in **separate model roots** (e.g., `header:default`, `footer:first`), they become fully functional parts of the editor model.

It means they are not just static HTML strings. You can render them in your application interface and bind them to the editor view, allowing users to **edit headers and footers** directly. The recommended approach is to use the [Multiroot editor](#ckeditor5/latest/examples/builds/multi-root-editor.html) or manually create editable UI views for these specific roots in a [Decoupled editor](#ckeditor5/latest/getting-started/setup/editor-types.html--decoupled-editor-document) setup.

By using the plugin described above together with a multi-root editor interface, users can import a Word document, edit the main content as well as headers and footers independently, and then export the entire updated document back to Word.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--known-limitations">

### Known limitations

* CKEditor 5 does not support lists with skipped intermediate levels.
* Due to lists merging in CKEditor 5, custom starting values are sometimes discarded by the editor.
* CKEditor 5 may overwrite some table borders with its built-in styles.
* Document headers and footers are not supported yet.
* For track changes and comments, check the [feature comparison guide](#ckeditor5/latest/features/converters/import-word/features-comparison.html--collaboration-features) for current development.
* The feature does not support `.doc` files.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--related-features">

### Related features

* The [paste from Word](#ckeditor5/latest/features/pasting/paste-from-office.html) feature allows you to paste content from Microsoft Word and keep the original structure and formatting.
* The [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature allows you to generate editable `.docx` files out of your editor-created content.
* The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature allows you to generate portable PDF files out of your editor-created content.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--common-api">

### Common API

The [ImportWord](../../../api/module%5Fimport-word%5Fimportword-ImportWord.html) plugin registers:

* The `'importWord'` UI button component that opens the native file browser to let you import a Word file directly from your disk.
* The `'importWord'` command implemented by the [ImportWordCommand](../../../api/module%5Fimport-word%5Fimportwordcommand-ImportWordCommand.html) that accepts the file to import.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--the-datainsert-event">

#### The `dataInsert` event

The [dataInsert](../../../api/module%5Fimport-word%5Fimportwordcommand-ImportWordCommand.html#event-dataInsert) event is fired by [ImportWordCommand](../../../api/module%5Fimport-word%5Fimportwordcommand-ImportWordCommand.html). It allows for modifying the HTML content before inserting it into the editor.

```
editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
    // The `data.html` property contains the HTML returned by the converter service.
    // Updating its value modifies the content that will be inserted into the editor.
    data.html = '<p>An example paragraph.</p>';
} );

```

Also, you can prevent the event from further processing, and stop the import, by calling the [event.stop()](../../../api/module%5Futils%5Feventinfo-EventInfo.html#member-stop) function.

```
editor.commands.get( 'importWord' ).on( 'dataInsert', ( event, data ) => {
    // Example: Do not insert the HTML if it contains a table.
    if ( data.html.includes( '<table' ) ) {
        event.stop();
    }
} );

```

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--rest-api">

### REST API

The DOCX to HTML converter provides an API for converting Microsoft Word `.docx` and `.dotx` files to HTML. Read the [REST API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Import-from-Word) to find out how to employ it in your implementation.

<a id="ckeditor5/latest/features/converters/import-word/import-word.html--collaboration-features-integration">

### Collaboration features integration

Import from Word automatically integrates with the [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) features if these features are enabled and configured in your editor setup.

When collaboration features are enabled, the `data` parameter in the `dataInsert` event may include the `comment_threads` and `suggestions` fields, which will hold data from the imported Word file.

<a id="ckeditor5/latest/features/custom-components.html">source file: "ckeditor5/latest/features/custom-components.html"</a>

## Custom widgets and components

CKEditor 5’s widget system allows developers to create custom interactive components that integrate with the editor’s content model. Widgets provide a structured way to embed complex content blocks, inline elements, data-driven components, and framework integrations within the editor.

The examples below demonstrate the functionality and implementation approaches for each widget type.

<a id="ckeditor5/latest/features/custom-components.html--block-widgets-self-contained-content-components">

### Block widgets: self-contained content components

Developers can build block widgets that create structured content blocks functioning as independent units within documents. The demo below shows a created from scratch simple block widget with title and description slots. You can [learn how to build block widgets](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html) in our framework section.

**Example components developers can build:**

* Product displays with images, pricing, and purchase options,
* Team member profiles with photos and contact information,
* Content cards for articles, case studies, and news items,
* Data visualization components and interactive charts,
* Alert boxes, callouts, and feature highlights.

<a id="ckeditor5/latest/features/custom-components.html--inline-widgets-dynamic-elements-within-text">

### Inline widgets: dynamic elements within text

Developers can create inline widgets as interactive elements that integrate seamlessly within text content without disrupting document flow. The demo below shows a simple and custom build placeholder feature. We have more advanced version of this feature, [Merge fields](#ckeditor5/latest/features/merge-fields.html), but this serves as a good example of what’s possible. You can [learn how to build inline widgets](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html) in our framework section.

**Example components developers can build:**

* Dynamic data displays for pricing, stock information, or weather,
* User mentions and employee directory references,
* Status indicators for project phases and workflows,
* Badge elements for ratings, certifications, and labels,

<a id="ckeditor5/latest/features/custom-components.html--external-data-widgets-live-updating-components">

### External data widgets: live updating components

Developers can build widgets that connect to external APIs and data sources to display real-time information directly within editor content. The editor below contains a widget that fetches data from an external source and updates all its instances in a set interval of time. In this particular example, the widget shows the current Bitcoin rate. You can [learn how to build widgets with external data](#ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html) in our framework section.

**Example components developers can build:**

* Financial data including stock prices and market indicators,
* Business metrics and KPI dashboards,
* Live feeds from social media, news sources, and events,
* Inventory systems with product availability and pricing,
* API integrations for CRM data and system notifications,
* Analytics displays with traffic and conversion metrics.

<a id="ckeditor5/latest/features/custom-components.html--react-and-other-frameworks-components-in-widgets-modern-ui-integrations">

### React (and other frameworks) components in widgets: modern UI integrations

Developers can integrate components from popular UI frameworks like React, Vue, Angular, and others into CKEditor 5, enabling reuse of existing component libraries and business logic. The editor below presents integration between React library and a block widget from the CKEditor ecosystem. You can [learn how to build widgets with React](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html) in our framework section.

**Example applications developers can build:**

* Design system component integration across frameworks,
* Complex multi-step forms and configuration panels that streamline content creation workflows.

While CKEditor 5 provides an example React integration, similar patterns can be applied to other frameworks when building custom widgets.

<a id="ckeditor5/latest/features/custom-components.html--more-complex-features-components-and-editors-ui">

### More complex features: components and editor’s UI

Developers can build sophisticated features that go beyond simple content widgets to include rich interactive UI elements like balloons, dropdowns, and contextual panels. These features combine content modeling, conversion pipelines, commands, and custom UI components to create seamless editing experiences. The demo below shows an abbreviation feature that presents a balloon panel for user input when adding abbreviations to text. You can [learn how to build features with balloon UI](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html) in our framework section.

<a id="ckeditor5/latest/features/custom-components.html--architecture-overview">

### Architecture overview

CKEditor 5’s architecture provides a comprehensive framework for building complex features that integrate content handling with sophisticated user interfaces:

**[Schema system](#ckeditor5/latest/framework/architecture/editing-engine.html--schema)** – Defines content structure, validation rules, and element relationships to ensure data integrity and feature compatibility.

**[Conversion pipeline](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion)** – Transforms data between the model, editing view, and data view, enabling seamless integration with external formats and real-time collaboration.

**[Command architecture](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands)** – Implements user actions, business logic, and state management with built-in undo/redo support and collaboration-ready operation handling.

**[UI integration](#ckeditor5/latest/framework/architecture/ui-library.html)** – Supports toolbar buttons, [contextual balloons](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree), dropdowns, and custom panel elements with automatic [focus management](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html) and accessibility features.

**[Event system](#ckeditor5/latest/framework/deep-dive/event-system.html)** – Provides a robust foundation for inter-component communication, user interaction handling, and plugin coordination through observable patterns.

**[Plugin architecture](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--plugins)** – Enables modular feature development with dependency management, lifecycle hooks, and seamless integration with existing editor functionality.

<a id="ckeditor5/latest/features/document-outline.html">source file: "ckeditor5/latest/features/document-outline.html"</a>

## Document outline

The document outline feature displays the list of sections (headings) of the document next to the editor. The outline updates automatically as the user works on the document. It offers quick navigation to a specific section upon clicking.

<a id="ckeditor5/latest/features/document-outline.html--demo">

### Demo

When the feature is enabled and configured, the outline can be displayed next to the document as presented below. The placement of the outline is [configurable](#ckeditor5/latest/features/document-outline.html--configuration) and depends on the HTML structure of the integration. The demo below showcases one of the recommended integrations but more are possible. See the [demo code](#ckeditor5/latest/features/document-outline.html--demo-code) to learn more.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/document-outline.html--demo-code">

#### Demo code

For the best user experience the document outline feature requires some effort from integrators. Because it renders independently from the rest of the editor user interface (toolbar, edited content), its placement, dimensions, and behavior (like toggling) depend on the layout and functionality of the web page.

The presented demo is a custom UI built on top of the [DecoupledEditor](../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) (similar to the [document editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html)). The editor in this demo loads:

* A set of common editor plugins ([Essentials](../api/module%5Fessentials%5Fessentials-Essentials.html), [Bold](../api/module%5Fbasic-styles%5Fbold-Bold.html), [Heading](../api/module%5Fheading%5Fheading-Heading.html), etc.).
* The [DocumentOutline](../api/module%5Fdocument-outline%5Fdocumentoutline-DocumentOutline.html) plugin.
* A custom `DocumentOutlineToggler` plugin created for this particular demo to allow toggling the visibility of the outline (learn more in the [step-by-step tutorial](#ckeditor5/latest/framework/tutorials/crash-course/editor.html)).

You can find the entire integration code below.

View the editor configuration script View the page layout and styles 

```
<div class="demo-container">
    <div class="toolbar-container"></div>
    <div class="document-outline-container"></div>
    <div class="editor-content-wrapper">
        <div class="editor-content">
            <p>Initial content of the editor</p>
        </div>
    </div>
</div>

<style>
    /* ----------------------- Demo layout styles ------------------------------ */

    .demo-container {
        display: grid;
        grid-template-columns: minmax(250px,.5fr) 1.5fr;
        grid-template-rows: auto 1fr;
        gap: 0px 0px;
        grid-template-areas:
            "Toolbar Toolbar"
            "Sidebar Content";
        background: var(--ck-color-base-foreground);
        border: 1px solid var(--ck-color-base-border);
        margin: 1.5em 0;

        /* The max height of the editor content wrapper before it becomes scrollable. */
        --demo-content-height: 800px;
    }

    .demo-container .toolbar-container {
        grid-area: Toolbar;
        box-shadow: 0 2px 3px hsla(0, 0%, 0%, 0.078);

        /* Makes the shadow display over the editor content. */
        position: relative;
    }

    /* Adjust borders of the toolbar to fit well into the layout. Avoid duplicated borders. */
    .demo-container .toolbar-container > .ck.ck-toolbar {
        border-bottom-right-radius: 0;
        border-bottom-left-radius: 0;
        border-top: 0;
        border-left: 0;
        border-right: 0;
    }

    .demo-container .editor-content-wrapper {
        grid-area: Content;
        max-height: var(--demo-content-height);
        overflow-y: auto;

        /* Center the editor content in this grid area. */
        display: flex;
        justify-content: center;
        align-items: flex-start;
    }

    .demo-container .document-outline-container {
        grid-area: Sidebar;
        max-height: var(--demo-content-height);
        overflow-y: auto;
        display: flex;
        flex-direction: column;
        padding: var(--ck-spacing-large) 0 0;

        /* Customize the default font size of the outline */
        --ck-document-outline-base-font-size: 1em;
    }

    /* ------------ DocumentOutlineToggler plugin styles ------------------- */

    /* Styles of the topmost demo container when the outline gets collapsed. */
    .demo-container.collapsed {
        grid-template-columns: 50px 1fr;
    }

    /* Styles of the outline when it gets collapsed. */
    .demo-container.collapsed .document-outline-container .ck-document-outline {
        width: 0px;
        margin: 0;
        padding: 0;
        overflow: hidden;
        height: 0;
    }

    /* Styles of the outline collapse button. */
    .demo-container .document-outline-container .ck-document-outline-toggle {
        align-self: flex-start;
        opacity: .5;
        margin-left: var(--ck-spacing-large);
        border-radius: 100%;
    }

    .demo-container .document-outline-container .ck-document-outline-toggle:hover {
        opacity: 1;
    }

    /* ----------------------- Content styles ------------------------------ */

    /* Styles of the editor content container to make it look like a sheet of paper. */
    .ck.ck-content {
        max-width: calc( 210mm + 2px );
        min-height: calc( 210mm + 2px );
        height: auto;
        padding: 20mm 12mm;
        box-sizing: border-box;
        background: hsl( 0, 0%, 100% );
        box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
        margin: calc( 2 * var(--ck-spacing-large) );
        overflow: hidden;
        flex: 1 1 auto;
    }

    .ck.ck-content,
    .ck.ck-content.ck-focused {
        border: 1px solid hsl( 0, 0%, 88% );
        box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
    }

    /* Vertical rhythm of the blocks in the editor content below. */
    .ck.ck-content h2 {
        font-size: 2.06em;
        line-height: 1.58em;
        padding-top: 0.455em;
        margin-bottom: 0.333em;
    }

    .ck.ck-content h3 {
        font-size: 1.75em;
        line-height: 1.86em;
        padding-top: 0.571em;
        margin-bottom: 0.357em;
    }

    .ck.ck-content h4 {
        font-size: 1.44em;
        line-height: 1.13em;
        padding-top: 0.217em;
        margin-bottom: 0.913em;
    }

    .ck.ck-content h5 {
        font-size: 1.19em;
        line-height: 1.37em;
        padding-top: 0.368em;
        margin-bottom: 1.00em;
    }

    .ck.ck-content p {
        font-size: 1.00em;
        line-height: 1.63em;
        padding-top: 0.500em;
        margin-bottom: 1.13em;
    }
</style>

```

<a id="ckeditor5/latest/features/document-outline.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/document-outline.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/document-outline.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/document-outline.html--configuring-the-container">

#### Configuring the container

The container element is essential for the document outline to render. You should pass the reference to the container element in the [config.documentOutline.container](../api/module%5Fdocument-outline%5Fdocumentoutline-DocumentOutlineConfig.html#member-container) configuration option.

```
documentOutline: {
    // Make sure the .document-outline-container element exists when the editor is being created.
    container: document.querySelector( '.document-outline-container' )
}

```

<a id="ckeditor5/latest/features/document-outline.html--customizing-the-look">

#### Customizing the look

The look of the document outline can be customized using CSS classes and custom properties. In the demo below, the following customizations were applied:

* The indentation of outline items was reduced (custom properties: `--ck-document-outline-indent-level-[2-3]`).
* The active item color was changed (`--ck-document-outline-item-active-color` custom property).
* The font size and line height were reduced for a more compact look (`.ck-document-outline__item` CSS class).
* Different bullets were added for each level for better readability (`.ck-document-outline__item_level-[2-3]` CSS classes).
View the document outline customization code 

```
.customization-demo {
    --ck-document-outline-indent-level-2: 1.1em;
    --ck-document-outline-indent-level-3: 2.2em;
    --ck-document-outline-item-active-color: hsl(340deg 82% 52%);
}

.customization-demo .ck-document-outline__item {
    line-height: 1.1em;
}

.customization-demo .ck-document-outline__item::before {
    margin: 0 .2em 0 0;
}

.customization-demo .ck-document-outline__item.ck-document-outline__item_level-2::before,
.customization-demo .ck-document-outline__item.ck-document-outline__item_level-5::before {
    content: "•";
}

.customization-demo .ck-document-outline__item.ck-document-outline__item_level-3 {
    font-size: .9em;
}

.customization-demo .ck-document-outline__item.ck-document-outline__item_level-3::before,
.customization-demo .ck-document-outline__item.ck-document-outline__item_level-6::before {
    content: "‣";
}

.customization-demo .ck-document-outline__item.ck-document-outline__item_level-4,
.customization-demo .ck-document-outline__item.ck-document-outline__item_level-5,
.customization-demo .ck-document-outline__item.ck-document-outline__item_level-6 {
    font-size: .8em;
}

.customization-demo .ck-document-outline__item.ck-document-outline__item_level-4::before {
    content: "⁃";
}

```

<a id="ckeditor5/latest/features/document-outline.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you navigate the content of the editor:

* [Table of contents](#ckeditor5/latest/features/table-of-contents.html) – Insert a table of contents widget into the document.
* [Content minimap](#ckeditor5/latest/features/minimap.html) – Navigate the document using a miniature overview map placed next to the editor.
* [Pagination](#ckeditor5/latest/features/pagination/pagination.html) – See the live preview of the document’s page breaks and quickly navigate between pages.

<a id="ckeditor5/latest/features/drag-drop.html">source file: "ckeditor5/latest/features/drag-drop.html"</a>

## Drag and drop

The drag and drop feature lets you drag and drop both text and content blocks such as paragraphs, tables, or lists inside the editor. This allows you to select an entire block or multiple blocks, and move them before or after other blocks. You can also drag and drop HTML and plain text content from outside the editor and use it to upload images.

<a id="ckeditor5/latest/features/drag-drop.html--demo">

### Demo

The demo below lets you drag contacts from the list to the editor. The contacts are inserted into the editor as custom widgets representing the [h-card microformat](http://microformats.org/wiki/h-card). You can also select and drag around existing content inside the editor.

Photos: [Wikipedia.org](http://en.wikipedia.org).

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

The source code of the above snippet is available here: [drag-drop.js](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-clipboard/docs/%5Fsnippets/features/drag-drop.js), [drag-drop.html](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-clipboard/docs/%5Fsnippets/features/drag-drop.html). You can find the configuration of the editor used in the demo here: [build-drag-drop-source.js](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-clipboard/docs/%5Fsnippets/features/build-drag-drop-source.js). The code for the custom plugin responsible for handling the h-cards is available here: [hcard.js](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-clipboard/docs/%5Fsnippets/features/hcard.js).

<a id="ckeditor5/latest/features/drag-drop.html--file-upload-via-drag-and-drop">

### File upload via drag and drop

When the [CKBox file manager](#ckeditor5/latest/features/file-management/ckbox.html) is enabled in your CKEditor 5 integration, you can upload files and images using the drag and drop mechanism. You can test this solution in the [CKBox demo](#ckeditor5/latest/features/file-management/ckbox.html--demo).

<a id="ckeditor5/latest/features/drag-drop.html--drag-and-drop-of-content-blocks">

### Drag and drop of content blocks

The drag and drop plugin fully supports dragging content blocks such as paragraphs, tables, or lists inside the editor by default. This allows you to select an entire block or multiple blocks, and move them before or after other blocks.

The drag and drop functions include:

* Selection of the text, elements, multiple blocks, and moving these around.
* Placement of blocks inside other blocks such as tables, blockquotes, etc.
* The braille dots panel icon  in the [balloon block editor](#ckeditor5/latest/features/drag-drop.html--balloon-block-editor-demo) now behaves as a drag handle.

<a id="ckeditor5/latest/features/drag-drop.html--classic-editor-demo">

#### Classic editor demo

Select a block or blocks, and drag them across the document. You can place blocks inside other blocks, such as tables and blockquotes.

<a id="ckeditor5/latest/features/drag-drop.html--balloon-block-editor-demo">

#### Balloon block editor demo

In the balloon block editor, you can also drag content blocks using the drag handle. Select or focus on the block, and then drag the block with the braille dots panel icon .

<a id="ckeditor5/latest/features/drag-drop.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

The [DragDrop](../api/module%5Fclipboard%5Fdragdrop-DragDrop.html) plugin will activate along with the clipboard plugin.

<a id="ckeditor5/latest/features/drag-drop.html--styling-the-drag-and-drop">

### Styling the drag and drop

The drag and drop target line color is managed by the CSS variable (`--ck-clipboard-drop-target-color`). You can use the following snippet to change the color of the line:

```
:root {
    --ck-clipboard-drop-target-color: green;
}

```

<a id="ckeditor5/latest/features/drag-drop.html--related-features">

### Related features

* CKEditor 5 supports dropping images from the file system thanks to the [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html) feature.

<a id="ckeditor5/latest/features/drag-drop.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-clipboard>.

<a id="ckeditor5/latest/features/editor-placeholder.html">source file: "ckeditor5/latest/features/editor-placeholder.html"</a>

## Editor placeholder

You can prompt the user to input content by displaying a configurable placeholder text when the editor is empty. This works similarly to the native DOM [placeholder attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-placeholder) used by inputs. Not to be confused with the content placeholders offered by the [merge fields](#ckeditor5/latest/features/merge-fields.html) feature.

<a id="ckeditor5/latest/features/editor-placeholder.html--demo">

### Demo

See the demo of the placeholder feature:

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/editor-placeholder.html--installation">

### Installation

The editor placeholder feature does not require a separate plugin installation. It does, however, require configuring the editor before use. There are two different ways of configuring the editor placeholder text:

<a id="ckeditor5/latest/features/editor-placeholder.html--using-the-placeholder-attribute-of-a-textarea">

#### Using the `placeholder` attribute of a textarea

Set the `placeholder` attribute on a `<textarea>` element passed to the `Editor.create()` method (for instance [ClassicEditor.create()](../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#static-function-create)) to configure the placeholder:

```
<textarea id="editor" placeholder="Type the content here!"></textarea>

```

<a id="ckeditor5/latest/features/editor-placeholder.html--using-the-editor-configuration">

#### Using the editor configuration

You can use the [editor.config.root.placeholder](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-root) configuration option:

* when no element was passed into `Editor.create()` method,
* when the element passed into `Editor.create()` was not a `<textarea>` (for instance, a `<div>` element),
* to override the `placeholder` text of a `<textarea>`, if one was passed into `Editor.create()` but the placeholder text should be different.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        root: {
            placeholder: 'Type the content here!'
        }
    } )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

```

If your editor implementation uses multiple roots, configure placeholders using `roots.<rootName>.placeholder`:

```
MultiRootEditor
    .create( {
        roots: {
            header: {
                placeholder: 'Type header...',
                element: document.querySelector( '#header' )
            },
            content: {
                placeholder: 'Type content...',
                element: document.querySelector( '#content' )
            },
            leftSide: {
                placeholder: 'Type left-side...',
                element: document.querySelector( '#left-side' )
            },
            rightSide: {
                placeholder: 'Type right-side...',
                element: document.querySelector( '#right-side' )
            }
        }
    } )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

```

<a id="ckeditor5/latest/features/editor-placeholder.html--styling-the-placeholder">

### Styling the placeholder

The editor placeholder text is displayed using a CSS pseudo–element (`::before`) related to the first empty element in the editor content (usually a paragraph). You can use the following snippet to change the appearance of the placeholder:

```
.ck.ck-editor__editable > .ck-placeholder::before {
    color: #d21714;
    font-family: Georgia;
}

```

**Note**: The `.ck-placeholder` class is also used to display placeholders in other places, for instance, [image captions](#ckeditor5/latest/features/images/images-captions.html). Make sure your custom styles apply to the right subset of placeholders.

<a id="ckeditor5/latest/features/editor-placeholder.html--changing-the-placeholder">

### Changing the placeholder

The editor placeholder could be updated at runtime by changing the `placeholder` property in the editing root.

```
editor.editing.view.document.getRoot( 'main' ).placeholder = 'new placeholder';

```

<a id="ckeditor5/latest/features/editor-placeholder.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core>.

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html">source file: "ckeditor5/latest/features/email-editing/email-configuration-helper.html"</a>

## Email configuration helper

While configuring an email editor looks like a demanding task, the email configuration helper plugin is the best way to start and make this experience more manageable.

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--demo">

### Demo

Look at the logs below to see the configuration problems.

The logs displayed below come from DevTools and show problems encountered by the editor during configuration validation. These issues may cause emails to be displayed incorrectly in various email clients.

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--email-configuration-devtools"> 

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings">

#### Logs and warnings

The [EmailConfigurationConfig](../../api/module%5Femail%5Femailconfigurationconfig-EmailConfigurationConfig.html) property lets you suppress warnings or log messages about email client compatibility.

```
ClassicEditor
    .create( {
        email: {
            logs: {
                suppressAll: false,
                suppress: [
                    'email-configuration-unsupported-reversed-list',
                    'email-configuration-unsupported-list-style-type',
                    // ... other message codes
                ]
            }
        }
    } )

```

<a id="ckeditor5/latest/features/email-editing/email-configuration-helper.html--common-api">

### Common API

The [EmailConfigurationHelper](../../api/module%5Femail%5Femailconfigurationhelper-EmailConfigurationHelper.html) plugin registers the following components:

* The [EmailConfigurationHelper](../../api/module%5Femail%5Femailconfigurationhelper-EmailConfigurationHelper.html) component.
* The [EmailConfigurationConfig](../../api/module%5Femail%5Femailconfigurationconfig-EmailConfigurationConfig.html) property.

<a id="ckeditor5/latest/features/email-editing/email.html">source file: "ckeditor5/latest/features/email-editing/email.html"</a>

## Email editing in CKEditor 5

CKEditor 5 provides a wide variety of tools and functions for editing almost any kind of content. This, too, includes email editing. However, creating and editing emails is a demanding task that needs a proper configuration. This is due to a variety of software products and a lack of a standardized approach. The email editing solution is a set of tools aimed at making the email composition a better and more effective experience.

<a id="ckeditor5/latest/features/email-editing/email.html--demo">

### Demo

Use the demo below to see the feature in action. Click the layout table  toolbar button to insert a new layout table. It is useful in creating email templates. Experiment with the newsletter content - see how it looks in the editor and the source HTML.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/email-editing/email.html--setting-up-your-email-editor">

### Setting up your email editor

A good email editor is a versatile, advanced software solution and as such, it needs several additional features. A set of CKEditor 5 plugins forms the full experience. Below is a list of all email-assisting features that may be useful when preparing a full-fledged email editor.

<a id="ckeditor5/latest/features/email-editing/email.html--email-configuration-helper">

#### Email configuration helper

The [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html) features provides a comprehensive set of tools for email composition and editing. It helps overcome various semantic and technical difficulties by:

* Verifying editor configuration for email compatibility.
* Ensuring proper HTML structure for email clients.
* Managing content restrictions specific to email formats.
* Providing warnings about unsupported features in email clients.

Using this feature alongside export with inline styles ensures your email content not only looks correct but also follows email-specific best practices and technical requirements. Learn how to configure it in the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html) guide.

<a id="ckeditor5/latest/features/email-editing/email.html--layout-tables-plugin">

#### Layout tables plugin

The [layout tables](#ckeditor5/latest/features/tables/layout-tables.html) feature provides specialized layout tables that are specifically designed for structuring email content, as opposed to presenting data in traditional content tables. For optimal email template development, we recommend using the [TableLayout](../../api/module%5Ftable%5Ftablelayout-TableLayout.html) plugin alongside the export with inline styles feature.

Layout tables created using the `TableLayout` plugin:

* Have `role="presentation"` for better accessibility.
* Include proper styling optimized for email layouts (100% width, proper borders, and padding).
* Maintain their appearance when exported with inline styles.

This is particularly important for email templates where table-based layouts are still the standard practice. The combination of layout tables and inline styles export ensures that your email templates maintain their structure and appearance across different email clients.

Learn how to configure it in the [Layout tables](#ckeditor5/latest/features/tables/layout-tables.html) guide.

<a id="ckeditor5/latest/features/email-editing/email.html--export-with-inline-styles-plugin">

#### Export with inline styles plugin

The export inline styles feature turns the editor’s global CSS styles into inline styles for DOM elements. For example, a global `<p class="red">` style defining the font color to be red will be turned into `<p style="color: red">`. Learn how to configure it in the [export with inline styles](#ckeditor5/latest/features/export-with-inline-styles.html--configuration) guide.

<a id="ckeditor5/latest/features/email-editing/email.html--email-specific-style-transformations">

##### Email-specific style transformations

For email-specific use cases, the package provides dedicated transformations through the [getEmailInlineStylesTransformations()](../../api/module%5Femail%5Femailinlinestylestransformations.html#function-getEmailInlineStylesTransformations) function. These transformations improve compatibility with email clients by converting modern CSS properties to better-supported HTML attributes.

To use these transformations, import the function and include it in your editor configuration:

The provided transformations handle the following email-specific styling conversions:

1. Float to align attribute:

  * `<img style="float: left">` → `<img style="float: left" align="left">`
  * `<table style="float: right">` → `<table style="float: right" align="right">`
2. Table centering via auto margins:

  * `<table style="margin-left: auto; margin-right: auto">` → `<table style="..." align="center">`

These transformations ensure better rendering consistency across various email clients that may have limited CSS support but respect traditional HTML attributes.

You can also combine these email transformations with your own custom transformations:

```
ClassicEditor
    .create( {
        plugins: [ ExportInlineStyles, /* ...other plugins */ ],
        exportInlineStyles: {
            transformations: [
                ...getEmailInlineStylesTransformations( {
                    // Transform figure elements to tables for better email client compatibility.
                    useFigureToTableFallback: true
                } ),
                // Your additional custom transformations.
                ( element, stylesMap ) => {
                    if ( element.tagName === 'A' ) {
                        stylesMap.set( 'text-decoration', 'underline' );
                    }
                }
            ]
        }
    } );

```

<a id="ckeditor5/latest/features/email-editing/email.html--plain-table-output">

#### Plain table output

This feature strips the table data from the `<figure>` tag and moves all applied attributes to the `table` element. This is because this tag is not supported by most popular email clients and removing it ensures compatibility. Learn more about this plugin in the [Plain table output](../../api/module%5Ftable%5Fplaintableoutput-PlainTableOutput.html) API guide.

<a id="ckeditor5/latest/features/email-editing/email.html--merge-fields-plugin">

#### Merge fields plugin

Merge fields are visually distinct placeholder elements, which you may put into the content to mark places, where real values should be inserted. This is perfect for creating document templates and other kinds of personalized content. Learn how to configure it in the [Merge fields](#ckeditor5/latest/features/merge-fields.html--configuration) guide.

<a id="ckeditor5/latest/features/email-editing/email.html--template-plugin">

#### Template plugin

The template plugin allows you to create and manage templates in the editor. It provides a user-friendly interface for selecting and applying templates to your content. It is useful for creating consistent email designs and layouts. Learn how to configure it in the [Templates](#ckeditor5/latest/features/template.html--configuration) guide.

<a id="ckeditor5/latest/features/email-editing/email.html--empty-block-plugin">

#### Empty block plugin

The [EmptyBlock](../../api/module%5Fhtml-support%5Femptyblock-EmptyBlock.html) plugin removes the `&nbsp;` fillers added by default to empty block elements like paragraphs. In some cases, such as loading legacy content, this prevents inconsistent rendering across email clients and interference with the CSS styling.

Here is how empty blocks are handled with and without the plugin:

```
<!-- Without EmptyBlock plugin -->
<p class="spacer">&nbsp;</p>
<td>&nbsp;</td>

<!-- With EmptyBlock plugin -->
<p class="spacer"></p>
<td></td>

```

To enable the EmptyBlock plugin, add it to your editor configuration:

The `preserveEmptyBlocksInEditingView` option determines whether empty blocks should be preserved during editing (`true`) or only in the final output (`false`).

<a id="ckeditor5/latest/features/email-editing/email.html--known-issues">

### Known issues

Email rendering can vary significantly between different email clients due to inconsistent HTML and CSS support. What looks perfect in one client may appear broken in another. Always test your emails in various popular clients and devices before sending them to ensure consistent appearance and functionality across platforms.

* Email clients’ default styles can significantly impact the rendering of your content. Even small changes like adding the `<!DOCTYPE html>` preamble to your email can dramatically alter the appearance of your content. However, many email clients use their rendering engines and may ignore the `DOCTYPE` altogether. Including it does not cause harm and is considered a best practice.
* Email clients do not support all color modes available in the editor. If you intend to use, for example, the [font color or font background color](#ckeditor5/latest/features/font.html) features in your editor, please [set the color picker](#ckeditor5/latest/features/font.html--color-picker) to `hex` mode for optimal compatibility.
* Most email clients offer no support for alpha channel settings in the `rgb` color mode.

<a id="ckeditor5/latest/features/email-editing/email.html--related-features">

### Related features

Here are some related CKEditor 5 features that you may find helpful:

* [Export with inline styles](#ckeditor5/latest/features/export-with-inline-styles.html) – The export with inline styles feature turns all external CSS style sheets into inline styles, providing better compatibility with various email clients.
* [Layout tables](#ckeditor5/latest/features/tables/layout-tables.html) – Create layout tables optimized for email templates with proper structure and styling.
* [Plain table output](../../api/module%5Ftable%5Fplaintableoutput-PlainTableOutput.html) – This plugin strips the `<figure>` tag from the table data for email client compatibility.
* [Merge fields](#ckeditor5/latest/features/merge-fields.html) – Create placeholder elements in your content to replace later.
* [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) – Add support for additional HTML elements and attributes in your content.
* [Styles](#ckeditor5/latest/features/style.html) – Apply predefined styles to content elements that can be exported as inline styles.

<a id="ckeditor5/latest/features/emoji.html">source file: "ckeditor5/latest/features/emoji.html"</a>

## Emoji

The emoji feature lets you insert emojis into the document from the editor toolbar or while writing the content. The emojis are pulled from the CDN to lessen the editor load.

Since there is a large number of emojis, they have been conveniently divided into several categories for easier use, such as “Smileys & Expressions” or “Objects.” You may also search for a specific emoji using the search field.

<a id="ckeditor5/latest/features/emoji.html--demo">

### Demo

Use the emoji toolbar button  in the editor below to open a panel with a table of selectable emojis. You may also trigger the emoji UI while writing the content by typing the pre-configured `:` marker followed by at least two letters of desired emoji name. Then, you can either choose which emoji to insert from the suggestion list or select the `Show all emoji...` option to open the full panel. The marker must be preceded by a space to work.

There is an option to set the skin tone of the emojis next to the search field, too.

The selected emoji category and skin tone are remembered by the feature, so next time you invoke the panel, you can quickly insert an emoji of similar type.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/emoji.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

The [emoji plugin](../api/module%5Femoji%5Femoji-Emoji.html) consists of two sub-plugins:

* [EmojiMention](../api/module%5Femoji%5Femojimention-EmojiMention.html) – Adds support for triggering the emoji UI dropdown while writing the content when you type a pre-configured `:` marker followed by at least two letters of the desired emoji name.
* [EmojiPicker](../api/module%5Femoji%5Femojipicker-EmojiPicker.html) – Registers the UI button component, which opens a panel with a table of selectable emojis.

You can freely choose how to load the feature: either as a whole (as shown in the example above) or select one of the sub-plugins if you need only one of the ways of inserting emojis into the document.

<a id="ckeditor5/latest/features/emoji.html--configuration">

### Configuration

The feature can be configured via the [config.emoji](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html) object.

* `dropdownLimit` – the number of items to appear in the emoji dropdown.  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        emoji: {  
            dropdownLimit: 5  
        }  
    } )  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```
* `skinTone` – the initial skin tone for the emojis that support skin tones.  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        emoji: {  
            skinTone: 'medium'  
        }  
    } )  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```
* `definitionsUrl` – the URL to the emoji definitions file. The URL should return a JSON array with emoji definitions specified by the [EmojiCdnResource](../api/module%5Femoji%5Femojirepository-EmojiCdnResource.html) interface.  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        emoji: {  
            definitionsUrl: 'https://example.com/emoji-definitions.json'  
        }  
    } )  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```
* `version` – the emoji database version. By default, version 16 is used. This option is ignored if the `definitionsUrl` setting is provided.  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        emoji: {  
            version: 15  
        }  
    } )  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```
* `useCustomFont` – if you customize the [emoji availability and appearance](#ckeditor5/latest/features/emoji.html--emoji-availability-and-appearance). It that case, it is highly recommended to disable the filtering mechanism because it uses a font built-in to your system.  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        emoji: {  
            useCustomFont: true  
        }  
    } )  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```

<a id="ckeditor5/latest/features/emoji.html--emoji-availability-and-appearance">

#### Emoji availability and appearance

The availability of the emoji depends on the operating system. Different systems will have different Unicode support. You may decide to lower the number of newer emoji by setting a lower [version](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-version) of Unicode of the emoji repository (CKEditor 5 hosts v15 and v16) or by providing a custom emoji repository using the [definitionsUrl](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-definitionsUrl). This way, the users with newer systems will not be able to use newer emojis. Keep in mind that this only affects the editor feature. A user will still be able to use the native emoji insertion methods. The availability may also increase with the usage of a custom font.

If you want to standardize the appearance of emoji accross operating systems, please consider using an external font in your integration, such as [Noto Color Emoji](https://fonts.google.com/noto/specimen/Noto+Color+Emoji). In the setup make sure to:

1. Set the `font-family` for the content, this way the emoji in the editable will use the custom font. For example:  
```  
body {  
    font-family: 'Lato', 'Noto Color Emoji', sans-serif;  
}  
```
2. Update the `--ck-font-face` variable, so that emoji in the picker and mention will use the custom font.  
```  
:root {
    --ck-font-face: Helvetica, Arial, Tahoma, Verdana, 'Noto Color Emoji';  
}  
```
3. Update the [editor configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) by adding the [emoji.useCustomFont](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-useCustomFont) option.  
```  
{  
    // ... Other configuration options ...  
    emoji: {  
        useCustomFont: true  
    }  
}  
```

<a id="ckeditor5/latest/features/emoji.html--emoji-source">

#### Emoji source

The database of English emoji is loaded by default from our CDN. Make sure that your [CSP rules](#ckeditor5/latest/getting-started/setup/csp.html) are correctly set up.

If you do not want to use our distribution and prefer to self-host emoji, you can use the [definitionsUrl](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-definitionsUrl) option. You can download the data directly from the package mentioned above or from our CDN, and place it under a static assets URL, for example:

1. Download the latest emoji database from <https://cdn.ckeditor.com/ckeditor5/data/emoji/16/en.json>, or download version 15 for older Unicode versions.
2. Place the downloaded file in your application’s assets folder, for example `public/emoji/en.json`. The specific location may vary depending on your framework and setup.
3. Update the configuration option `definitionsUrl` to point to the URL of your assets, for example: `https://example.com/emoji/en.json`.

You can prepare your own database with a different emoji set, but it must have an identical structure as ours. Otherwise, the Emoji feature will not work.

<a id="ckeditor5/latest/features/emoji.html--marker-conflicts">

#### Marker conflicts

The emoji feature uses the `:` marker that opens a panel with a table of selectable emojis. If you use the [mentions](#ckeditor5/latest/features/mentions.html) or [merge fields](#ckeditor5/latest/features/merge-fields.html) features, they can also show UI panels by pressing a pre-configured key. Those keys may conflict with the emoji feature. In such a case, the [EmojiMention](../api/module%5Femoji%5Femojimention-EmojiMention.html) plugin will not integrate the autocompletion mechanism.

To prevent conflicts, make sure that the [mention’s marker](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html#member-marker) and [merge field’s prefix](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-prefix) configuration options are not defined as `:`.

<a id="ckeditor5/latest/features/emoji.html--troubleshooting">

### Troubleshooting

If you are experiencing issues with the emoji feature in CKEditor 5 and the `emoji-repository-empty` is displayed in the console, it may be due to missing system support for emoji fonts or problems loading the emoji repository. Below are some common issues and their solutions.

<a id="ckeditor5/latest/features/emoji.html--no-emoji-font-installed">

#### No emoji font installed

**Problem**:  
The system does not have an emoji font installed, preventing the emoji feature from rendering emoji correctly.

**Solution**:  
To use the emoji feature, install an emoji font on your operating system:

* macOS: `Apple Color Emoji`
* Windows: `Segoe UI Emoji`
* Linux: `Noto Color Emoji` (or an alternative like `Twemoji`)

Once installed, restart your browser and reload the editor.

<a id="ckeditor5/latest/features/emoji.html--server-error-when-loading-the-emoji-repository">

#### Server error when loading the emoji repository

**Problem**:  
The request to load the emoji repository was completed, but the server returned an error (such as `404 Not Found`, or `500 Internal Server Error`).

**Solution**:

* Ensure the emoji repository URL is correct and accessible.
* If using a custom emoji repository, verify that it is properly configured.

<a id="ckeditor5/latest/features/emoji.html--network-issues-preventing-the-emoji-repository-from-loading">

#### Network issues preventing the emoji repository from loading

**Problem**:  
The emoji repository could not be loaded due to a network issue, CORS restriction, or blocked request.

**Solution**:

* Verify that the URL is correct and accessible.
* Check your internet connection.
* If applicable, update your Content Security Policy (CSP) settings to allow connections to the emoji repository.

For more details on configuring CSP, see the [Content Security Policy](#ckeditor5/latest/getting-started/setup/csp.html) guide.

By following these steps, you should be able to resolve common issues with the emoji plugin in CKEditor 5\. If problems persist, check your browser console for additional error messages or consult the CKEditor 5 [GitHub repository for support](https://github.com/ckeditor/ckeditor5/issues).

<a id="ckeditor5/latest/features/emoji.html--related-features">

### Related features

In addition to enabling the emoji feature, you may want to check the following related features:

* [Special characters](#ckeditor5/latest/features/special-characters.html) – Allows inserting **mathematical operators**, **currency symbols**, **punctuation**, **graphic symbols** (such as arrows or bullets), or Unicode letters typically not accessible from the keyboard (such as **umlauts** or **other diacritics**).
* [Mentions](#ckeditor5/latest/features/mentions.html) – Brings support for smart autocompletion.

<a id="ckeditor5/latest/features/emoji.html--common-api">

### Common API

The [EmojiPicker](../api/module%5Femoji%5Femojipicker-EmojiPicker.html) plugin registers the UI button component (`'emoji'`) and the command (`'emoji'`) that allows opening the emoji picker UI.

<a id="ckeditor5/latest/features/emoji.html--contribute">

### Contribute

The source code of the feature is available at GitHub in <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-emoji>.

<a id="ckeditor5/latest/features/export-with-inline-styles.html">source file: "ckeditor5/latest/features/export-with-inline-styles.html"</a>

## Export with inline styles

The export with inline styles feature applies the styles defined by CSS style sheets directly on HTML elements. For example, a global `<p class="red">` style defining the font color to be red, will be turned into `<p style="color: red">`. This is especially useful for email creation but may be helpful in other use cases.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--demo">

### Demo

Use the Source editing command  to see changes. Check the output below to see the exported content with inline styles applied.

Switch the tabs below to see three different outputs: the HTML tags with classes, CSS styles, and the HTML with those styles inlined. The last output shows how the exported content would look like.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--export-inline-styles-code-switcher"> 

The preview below shows the rendered content with inlined styles.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--snippet-export-preview"> 

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/export-with-inline-styles.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--configuration">

### Configuration

The export with inline styles feature can be configured using the `exportInlineStyles` configuration object:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportInlineStyles: {
            stylesheets: [ './path/to/custom-styles.css' ],
            inlineCss: `
                .ck-content {
                    .warning { color: red; }
                    .note { background: yellow; }
                }
            `,
            stripCssClasses: true
            // ...
        }
    } )

```

<a id="ckeditor5/latest/features/export-with-inline-styles.html--stylesheets">

#### Stylesheets

An array with paths to CSS files to process. The order matters as later files can override styles from earlier ones. In typical setups, provide explicit paths to all style sheets that should be used during export.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportInlineStyles: {
            stylesheets: [
                './path/to/base-styles.css',	// Processed first.
                './path/to/theme-styles.css',	// Can override base styles.
                './path/to/custom-styles.css'	// Has highest priority.
            ]
            // ...
        }
    } )

```

<a id="ckeditor5/latest/features/export-with-inline-styles.html--inline-css">

#### Inline CSS

A string containing CSS rules to apply after processing the external style sheets. Useful for adding supplemental styles without external files. The option defaults to an empty string.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportInlineStyles: {
            inlineCss: `
                .ck-content {
                    /* Styles directly applied to .ck-content */
                    color: blue;
                    font-family: Arial;

                    /* Nested styles for children */
                    .warning {
                        color: red;
                        font-weight: bold;
                    }
                    .highlight {
                        background: yellow;
                    }
                }
            `
            // ...
        }
    } )

```

<a id="ckeditor5/latest/features/export-with-inline-styles.html--strip-css-classes">

#### Strip CSS classes

When set to `true`, the feature will remove the CSS classes from elements after inline styles are applied. This ensures the exported content preserves styling without depending on external style sheets. The option defaults to `false`.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportInlineStyles: {
            stripCssClasses: true
            // ...
        }
    } )

```

<a id="ckeditor5/latest/features/export-with-inline-styles.html--transformations">

#### Transformations

An array of functions that allow you to modify the elements and their styles before applying inline styles. Each function receives the element and a `stylesMap` object, which contains the computed styles for that element. You can use this to add, remove, or modify styles based on your needs.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        exportInlineStyles: {
            transformations: [
                ( element, stylesMap ) => {
                    // Example transformation: Add a custom attribute to all paragraphs.
                    if ( element.tagName === 'P' ) {
                        element.setAttribute( 'data-paragraph', 'true' );
                    }
                }
            ]
            // ...
        }
    } )

```

We also provide a handy transformation helper for email creation use cases. These transformations improve compatibility with email clients by converting modern CSS properties to better-supported HTML attributes.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--usage">

### Usage

To export the editor content with inline styles, use the [ExportInlineStyles](../api/module%5Fexport-inline-styles%5Fexportinlinestyles-ExportInlineStyles.html) command:

```
editor.execute( 'exportInlineStyles' )
    .then( ( html ) => {
        console.log( html );
    } )
    .catch( ( error ) => {
        console.error( error );
    } );

```

You can also pass configuration options directly to the command. These options will override any editor configuration settings:

```
editor.execute( 'exportInlineStyles', {
    stylesheets: [ './path/to/custom-styles.css' ],
    inlineCss: '.ck-content .warning { color: red; }',
    stripCssClasses: true,
    transformations: [ /* custom transformations */ ]
} )
    .then( ( html ) => {
        console.log( html );
    } )
    .catch( ( error ) => {
        console.error( error );
    } );

```

The command outputs the exported content as an HTML string with inline styles applied. You can then use the content in email templates, CMS systems, or other environments where external CSS is not supported.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--style-transformations">

#### Style transformations

The export with inline styles feature allows you to apply custom transformations to elements before inline styles are applied. Transformations enable you to modify elements and their styles programmatically during the export process.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--when-transformations-are-invoked">

##### When transformations are invoked

Transformations are called for each element in the DOM tree during the export process:

1. Child elements are processed first, before their parent elements.
2. For each element, the transformation is executed immediately before inline styles are assigned to the element.

This execution order gives you powerful control over the exported content:

* You can modify the element’s attributes and styles just before they are finalized.
* You can add or remove styles from the `stylesMap` to customize the final appearance.
* You can manipulate the element’s children (add, remove, or modify) since they are already processed when the parent’s transformation is called.
* You can even remove elements completely from the output if needed.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--example-transformation">

##### Example transformation

```
transformations: [
    ( element, stylesMap ) => {
        // Add a new style.
        if ( element.tagName === 'P' ) {
            stylesMap.set( 'line-height', '1.5' );
        }

        // Remove a style.
        if ( element.classList.contains( 'no-margin' ) ) {
            stylesMap.delete( 'margin' );
        }

        // Modify child structure.
        if ( element.classList.contains( 'box' ) ) {
            // Remove unwanted child elements.
            const unwantedElements = Array.from( element.querySelectorAll( '.remove-me' ) );
            unwantedElements.forEach( el => el.remove() );

            // Add new child element.
            const disclaimer = document.createElement( 'div' );
            disclaimer.textContent = 'Important notice';
            element.appendChild( disclaimer );
        }
    }
]

```

This processing approach provides flexibility for implementing complex export logic while ensuring all styles are properly applied to the modified DOM structure.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--real-world-example">

#### Real-world example

Here is a simple example showing how to use this feature to export content for an email message:

```
// Button that exports the editor content for email use.
document.querySelector( '#export-for-email' ).addEventListener( 'click', () => {
    // Get content with inline styles with configuration options.
    editor.execute( 'exportInlineStyles', {
        // Specify which root to use (useful in multi-root editors).
        rootName: 'main',

        // Override editor configuration with email-specific settings.
        stylesheets: [ './email-styles.css' ],
        inlineCss: `
            .ck-content {
                font-family: Arial, sans-serif;
                .quote { font-style: italic; }
            }
        `,
        stripCssClasses: true,

        // Apply email-specific transformations.
        transformations: [
            ( element, stylesMap ) => {
                // Make all links color blue and underlined for better email client compatibility.
                if ( element.tagName === 'A' ) {
                    stylesMap.set( 'color', '#0066cc' );
                    stylesMap.set( 'text-decoration', 'underline' );
                }

                // Ensure all images have explicit width/height (helps with email rendering).
                if ( element.tagName === 'IMG' && !element.getAttribute( 'width' ) ) {
                    element.setAttribute( 'width', '300px' );
                    element.setAttribute( 'height', '100px' );
                }

                // Ensure paragraphs have margin for email spacing.
                if ( element.tagName === 'P' ) {
                    stylesMap.set( 'margin-bottom', '16px' );
                }
            }
        ],

        // Remove all classes to prevent dependency on external CSS.
        stripCssClasses: true
    } )
        .then( htmlWithInlineStyles => {
            // Use the exported content in your email sending logic.
            sendEmail( {
                subject: 'Newsletter',
                content: htmlWithInlineStyles,
                recipients: [ 'user@example.com' ]
            } );
        } )
        .catch( error => {
            console.error( 'Failed to export content:', error );
        } );
} );

// Example email sending function (would be replaced with your actual email API).
function sendEmail( emailData ) {
    console.log( 'Sending email with inline-styled content:', emailData );
    // Your email API call would go here:
    // emailAPI.send( emailData );
}

```

<a id="ckeditor5/latest/features/export-with-inline-styles.html--compatibility">

### Compatibility

<a id="ckeditor5/latest/features/export-with-inline-styles.html--supported-features">

#### Supported features

* Basic CSS properties (`color`, `background-color`, `font-family`, etc.)
* Compound properties (`background`, `margin`, `padding`, etc.)
* CSS variables (resolved during export)
* Simple CSS selectors (`class`, `id`, `element`)

Supported pseudo-classes:

* Structural pseudo-classes:  
  * `:first-child`
  * `:last-child`
  * `:nth-child()`
  * `:only-child`
  * `:empty`
  * `:nth-of-type()`
  * `:first-of-type`
  * `:last-of-type`
* Logical pseudo-classes:  
  * `:matches()`
  * `:not()`
  * `:is()`
* Root pseudo-class:  
  * `:root`

<a id="ckeditor5/latest/features/export-with-inline-styles.html--limited-or-unsupported-features">

#### Limited or unsupported features

* `media` queries
* `@import` and `@font-face` rules
* `@keyframes` and `animation` properties
* `transition` properties
* `:before` and `:after` pseudo-elements
* Interactive state pseudo-classes:  
  * `:focus`
  * `:visited`
  * `:link`
  * `:hover`
  * `:active`
* Shadow DOM and `::part()` selectors

<a id="ckeditor5/latest/features/export-with-inline-styles.html--related-features">

### Related features

Here are some other CKEditor 5 features that work well with the export with inline styles feature:

* [Email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html) – Ensure email-compatible content structure and validate against email client restrictions.
* [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) – Add support for additional HTML elements and attributes in your content.
* [Style](#ckeditor5/latest/features/style.html) – Apply predefined styles to content elements that can be exported as inline styles.
* [Layout tables](#ckeditor5/latest/features/tables/layout-tables.html) – Layout tables are used to structure a web page content spatially rather than for presenting tabular data.

<a id="ckeditor5/latest/features/export-with-inline-styles.html--common-api">

### Common API

The [ExportInlineStyles](../api/module%5Fexport-inline-styles%5Fexportinlinestyles-ExportInlineStyles.html) plugin registers the [ExportInlineStyles](../api/module%5Fexport-inline-styles%5Fexportinlinestyles-ExportInlineStyles.html) command.

It accepts the optional `rootName` configuration parameter, which determines the editor root to use for content origin.

<a id="ckeditor5/latest/features/feature-digest.html">source file: "ckeditor5/latest/features/feature-digest.html"</a>

## Feature digest

CKEditor 5 offers over 150 various features, from basic editing capabilities like bold or italics to full-blown real-time collaboration, where multiple people can work on one document at the same time. This page collects them all and groups them into capabilities, features, and sub-features. Let’s hope this list will help you grasp and easily digest everything CKEditor 5 has to offer.

<a id="ckeditor5/latest/features/feature-digest.html--core-editing">

### Core editing

Core editing capability provides tools to create, edit, and style content. Here are essentials that every writer needs in their tool belt, like bold or italics. There is also something for coders - advanced HTML editing capabilities where you can directly edit HTML elements.

<a id="ckeditor5/latest/features/feature-digest.html--advanced-html-editing">

#### Advanced HTML Editing

Advanced HTML Editing provides general HTML support, offering detailed control over permissible HTML elements, attributes, and styles. It further allows HTML Source Code Editing, handling HTML elements, HTML comments, and editing of the full page content, including meta tags.

<a id="ckeditor5/latest/features/feature-digest.html--block-formatting">

#### Block formatting

Block Formatting allows for the organization and emphasis of content through the use of Headings, Style Headings, Block Quotes, and Horizontal Lines. Users can select from different levels of headings to outline sections and subsections, apply various styles to these headings for visual hierarchy, insert horizontal lines to delineate sections, and use block quotes to highlight excerpts or important passages.

<a id="ckeditor5/latest/features/feature-digest.html--bookmarks">

#### Bookmarks

The bookmarks feature allows for adding and managing the bookmarks anchors attached to the content of the editor. These provide fast access to important content sections, and speed up the navigation boosting efficiency.

[Feature page](#ckeditor5/latest/features/bookmarks.html) 

<a id="ckeditor5/latest/features/feature-digest.html--clipboard">

#### Clipboard

Copy, cut, and paste content within the editor or from external sources.

[Feature page](#ckeditor5/latest/framework/deep-dive/clipboard.html) 

<a id="ckeditor5/latest/features/feature-digest.html--code-blocks">

#### Code blocks

Supports the insertion and management of pre-formatted code snippets with distinct styling.

[Feature page](#ckeditor5/latest/features/code-blocks.html) 

<a id="ckeditor5/latest/features/feature-digest.html--drag-and-drop">

#### Drag and drop

Rearrange elements within a document, including moving text blocks, images, or other content types.

[Feature page](#ckeditor5/latest/features/drag-drop.html) 

<a id="ckeditor5/latest/features/feature-digest.html--font-formatting">

#### Font formatting

The font feature lets you change font family, size, and color (including background color). All of these options are configurable.

<a id="ckeditor5/latest/features/feature-digest.html--image">

#### Image

The image feature allows adding images of various kinds to the rich content inside the editor. A large set of subfeatures lets the users fully control this process. Upload or paste images, insert via URL, use responsive images, resize images, add captions, set different image styles, and link images.

<a id="ckeditor5/latest/features/feature-digest.html--links">

#### Links

Facilitates the addition of hyperlinks to text, automatically converting typed or pasted URLs into clickable links, and allowing manual insertion and editing of links.

[Feature page](#ckeditor5/latest/features/link.html) 

<a id="ckeditor5/latest/features/feature-digest.html--lists">

#### Lists

Lists allow the creation and management of various list types, including to-do lists, bulleted and numbered lists, with additional customization options such as list styles, setting the start number for lists, creating reversed lists, adjusting list indentation, and crafting nested lists.

<a id="ckeditor5/latest/features/feature-digest.html--mermaid">

#### Mermaid

You can create flowcharts and diagrams in CKEditor 5 thanks to the experimental integration with the Mermaid library. Mermaid uses a Markdown-inspired syntax to create and dynamically modify flowcharts, Gantt diagrams, pie or quadrant charts, graphs, mindmaps, and more.

[Feature page](#ckeditor5/latest/features/mermaid.html) 

<a id="ckeditor5/latest/features/feature-digest.html--remove-formatting">

#### Remove formatting

The remove format feature lets you quickly remove any text formatting applied using inline HTML elements and CSS styles, like basic text styles (bold, italic) or font family, size, and color. This feature does not remove block-level formatting (headings, images) or semantic data (links).

[Feature page](#ckeditor5/latest/features/remove-format.html) 

<a id="ckeditor5/latest/features/feature-digest.html--select-all">

#### Select all

Enables the selection of all content within the editor with a single command or shortcut.

[Feature page](#ckeditor5/latest/features/select-all.html) 

<a id="ckeditor5/latest/features/feature-digest.html--tables">

#### Tables

CKEditor 5 provides robust support for tables, with the ability to merge and split cells, resize columns, style tables and individual cells, insert and delete columns and rows, as well as create nested tables for complex data presentation.

<a id="ckeditor5/latest/features/feature-digest.html--text-alignment">

#### Text alignment

Allows the adjustment of text alignment to the left, right, center, or justify and permits the alteration of indentation.

[Feature page](#ckeditor5/latest/features/text-alignment.html) 

<a id="ckeditor5/latest/features/feature-digest.html--text-formatting">

#### Text formatting

CKEditor 5 provides developers with text editing and formatting features such as Bold, Italic, Underline, Strikethrough, Subscript, Superscript, Inline Code, Highlight, and Font Styles. These features allow users to style and present their content as needed. This ensures users can style their text to improve readability, match branding guidelines, or highlight important content sections.

<a id="ckeditor5/latest/features/feature-digest.html--undoredo">

#### Undo/redo

Backtrack or repeat actions for editing purposes.

[Feature page](#ckeditor5/latest/features/undo-redo.html) 

<a id="ckeditor5/latest/features/feature-digest.html--collaboration">

### Collaboration

Collaborate with others - real-time or asynchronously. Comment, co-author, and mention team members in your documents. With collaboration features review process should be a breeze.

<a id="ckeditor5/latest/features/feature-digest.html--asynchronous-collaboration">

#### Asynchronous collaboration

Asynchronous Collaboration in CKEditor 5 is designed for teams using a turn-based approach to collaboratively write, review, and discuss content within the application. It integrates Track Changes, Comments, and Revision History features to facilitate collaboration.

<a id="ckeditor5/latest/features/feature-digest.html--comments">

#### Comments

Users can add side notes to marked fragments of the document, including text and block elements such as images. It also allows the users to discuss in threads and remove comments when they finish the discussion.

<a id="ckeditor5/latest/features/feature-digest.html--mentions">

#### Mentions

The mention feature supports smart autocompletion triggered by user input. Typing a predetermined marker, like @ or #, prompts a panel to appear, offering autocomplete suggestions.

[Feature page](#ckeditor5/latest/features/mentions.html) 

<a id="ckeditor5/latest/features/feature-digest.html--real-time-collaboration">

#### Real-time collaboration

Real-Time Collaboration in CKEditor 5 is designed for users who are writing, reviewing, and commenting on content simultaneously. It also automatically solves all conflicts if users make changes at the same time.

<a id="ckeditor5/latest/features/feature-digest.html--revision-history">

#### Revision history

The revision history feature is a document versioning tool. It allows CKEditor 5 users to create and view the chronological revision history of their content. These versions are listed in the side panel. The preview mode allows for easy viewing of content development between revisions. You can rename, compare, and restore older revisions on the go.

[Feature page](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) 

<a id="ckeditor5/latest/features/feature-digest.html--track-changes">

#### Track changes

The track changes feature brings automatic suggestion marking for the document as you change it. When editing the document, the user can switch to the track changes mode. All their changes will then create suggestions that they can accept or discard.

[Feature page](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) 

<a id="ckeditor5/latest/features/feature-digest.html--users-list-and-permissions">

#### Users list and permissions

The Users plugin and related plugins let you manage user data and permissions. This is essential when many users are working on the same document.

[Feature page](#ckeditor5/latest/features/collaboration/users.html) 

<a id="ckeditor5/latest/features/feature-digest.html--content-conversion-embedding">

### Content conversion & embedding

Collaborate also regarding different formats. With content conversions, you can integrate content across commonly used business formats. You can also enrich your content with media embeds.

<a id="ckeditor5/latest/features/feature-digest.html--content-generation">

#### Content generation

CKEditor 5 may be your universal starting point for generating content in several recognizable formats.

<a id="ckeditor5/latest/features/feature-digest.html--export-with-inline-styles">

#### Export with inline styles

The `ExportInlineStyles` plugin applies the styles defined by CSS style sheets directly on HTML elements.

[Feature page](#ckeditor5/latest/features/export-with-inline-styles.html) 

<a id="ckeditor5/latest/features/feature-digest.html--markdown-output">

#### Markdown output

Enable Markdown as the default output format instead of HTML with the Markdown plugin. Combined with Autoformatting, CKEditor becomes an efficient Markdown editor, allowing the creation of text documents using the simplified formatting syntax favored by developers.

[Feature page](#ckeditor5/latest/features/markdown.html) 

<a id="ckeditor5/latest/features/feature-digest.html--media-embed">

#### Media embed

Use the insert media button in the toolbar to embed media. Pasting a media URL directly into the editor content automatically embeds the media.

[Feature page](#ckeditor5/latest/features/media-embed.html) 

<a id="ckeditor5/latest/features/feature-digest.html--paste-markdown">

#### Paste Markdown

The paste Markdown feature lets users paste Markdown-formatted content straight into the editor. It will be then converted into rich text on the fly.

[Feature page](#ckeditor5/latest/features/pasting/paste-markdown.html) 

<a id="ckeditor5/latest/features/feature-digest.html--xml-output">

#### XML output

Turn your content into parsable XML files for automation and cross-platform interoperability.

[Feature page](../api/module%5Fengine%5Fdataprocessor%5Fxmldataprocessor-XmlDataProcessor.html) 

<a id="ckeditor5/latest/features/feature-digest.html--page-management">

### Page management

Format, organize, and navigate your documents easily with page management features. Create a table of contents, insert page breaks, and manage pagination.

<a id="ckeditor5/latest/features/feature-digest.html--document-outline">

#### Document outline

The Document Outline feature automatically detects and lists document headings in a sidebar, enabling faster navigation through large documents. Headings are organized in a structured list, so users can click and jump to different sections quickly. This feature also allows for customization of the outline’s location within the user interface, catering to different user preferences for workspace layout.

[Feature page](#ckeditor5/latest/features/document-outline.html) 

<a id="ckeditor5/latest/features/feature-digest.html--page-utilities">

#### Page utilities

CKEditor 5 Page Utilities enables users to dictate the structuring and print formatting of their documents effectively.

<a id="ckeditor5/latest/features/feature-digest.html--pagination">

#### Pagination

The Pagination feature visually indicates where pages begin and end within a document. This feature is designed to assist users in preparing their documents for printing or export to various document formats, ensuring that the transition between pages is seamless and accurately reflected in the final output. Users may adjust content distribution across pages as they like, ensuring well-organized documents with presented content, whether in digital form or print. By providing a clear view of how text and elements will appear page-by-page, Pagination aids in the creation of professional and polished documents.

[Feature page](#ckeditor5/latest/features/pagination/pagination.html) 

<a id="ckeditor5/latest/features/feature-digest.html--table-of-contents">

#### Table of contents

The Table of Contents feature is a dynamic tool for organizing documents. It allows for the insertion of a linked table of contents that automatically updates in real time as the document’s content changes. This means changes made to headings or structured sections within the document are reflected immediately in the table of contents, accurately representing the document structure.

[Feature page](#ckeditor5/latest/features/table-of-contents.html) 

<a id="ckeditor5/latest/features/feature-digest.html--productivity">

### Productivity

Speed up the content creation process with dedicated productivity utilities. The CKEditor AI feature brings generation, summarization, correction, translation, contextual chat help, reviews, and many other capabilities right into the editor.

<a id="ckeditor5/latest/features/feature-digest.html--ckeditor-ai">

#### CKEditor AI

By integrating AI writing assistance directly into the editing experience, CKEditor AI empowers authors with real-time AI writing support, streamlines content creation, and enhances editorial workflows across a wide range of use cases – from productivity boosts and proof-reading to content quality and consistency.

<a id="ckeditor5/latest/features/feature-digest.html--ai-assistant">

#### AI Assistant (legacy)

The AI Assistant feature enhances editing efficiency and creativity with artificial intelligence capabilities. It allows users to generate new content and process data through custom queries or utilize a set of predefined commands that are also customizable. The feature supports integration with multiple AI API providers: OpenAI, Azure OpenAI, and Amazon Bedrock. You can also integrate it with custom models.

[Feature page](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html) 

<a id="ckeditor5/latest/features/feature-digest.html--automation">

#### Automation

Automate your workflow with CKEditor 5 automation tools, regardless of whether you write, link, or save!

<a id="ckeditor5/latest/features/feature-digest.html--case-change">

#### Case change

The Case Change feature simplifies adjusting text cases within a document. With just a single click, users can shift text between UPPERCASE, lowercase, and Title Case options. The case transformation can be applied to various text blocks (paragraph, heading, or list item) by placing the cursor within the block. Alternatively, users can select a specific fragment of text they wish to modify. This feature enhances the editing workflow by removing the need for manual case adjustments.

[Feature page](#ckeditor5/latest/features/case-change.html) 

<a id="ckeditor5/latest/features/feature-digest.html--emoji">

#### Emoji

The Emoji feature lets you insert emojis into the document from the editor toolbar, or on the go while writing the content.

[Feature page](#ckeditor5/latest/features/emoji.html) 

<a id="ckeditor5/latest/features/feature-digest.html--find-and-replace">

#### Find and replace

The Find and Replace feature in CKEditor 5’s Productivity tools allows you to search for words or phrases in your document and replace them with different text. This function helps speed up editing and maintain content consistency.

[Feature page](#ckeditor5/latest/features/find-and-replace.html) 

<a id="ckeditor5/latest/features/feature-digest.html--format-painter">

#### Format painter

The Format Painter feature lets users clone formatting from one section and apply it to others within a document. This tool speeds up maintaining style consistency across the document. Once initiated, Format Painter can continue to apply the copied formatting to multiple sections consecutively. This “continuous painting” ensures a uniform style is achieved quickly without the need to repeatedly select the formatting options for each new section.

[Feature page](#ckeditor5/latest/features/format-painter.html) 

<a id="ckeditor5/latest/features/feature-digest.html--fullscreen-mode">

#### Fullscreen mode

The fullscreen mode lets you temporarily expand the editor to the whole browser viewport, giving you more space to comfortably edit content and use editor’s UI features.

[Feature page](#ckeditor5/latest/features/fullscreen.html) 

<a id="ckeditor5/latest/features/feature-digest.html--keyboard-shortcuts">

#### Keyboard shortcuts

CKEditor 5 supports various keyboard shortcuts that boost productivity and provide necessary accessibility to screen reader users.

[Feature page](#ckeditor5/latest/features/accessibility.html--keyboard-shortcuts) 

<a id="ckeditor5/latest/features/feature-digest.html--math-type">

#### MathType

Math Equations allows you to add properly formatted mathematical notation and chemical formulas to your documents. This feature supports the inclusion of math equations, which can be handwritten on a tablet and automatically converted into well-formed digital text. It also offers simple numbering of equations and the ability to customize with various fonts and colors, enhancing readability and presentation in your content.

[Feature page](#ckeditor5/latest/features/math-equations.html) 

<a id="ckeditor5/latest/features/feature-digest.html--merge-fields">

#### Merge fields

Merge Fields allows the inclusion of placeholders in your content, facilitating the creation of document templates, especially useful for email templates and document automation. These placeholders can later be replaced with dynamic values by the customer’s application, enabling tasks like mass email distribution or generation of personalized documents.

[Feature page](#ckeditor5/latest/features/merge-fields.html) 

<a id="ckeditor5/latest/features/feature-digest.html--paste-from-google-docs">

#### Paste from Google Docs

Paste from Google Docs allows you to paste content from Google Docs and preserve its original structure and formatting.

[Feature page](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) 

<a id="ckeditor5/latest/features/feature-digest.html--paste-from-office">

#### Paste from Office

Paste from Office features let you paste content from Microsoft Word and Microsoft Excel and preserve its original structure and formatting. This is the basic, open-source Paste from Office feature.

[Feature page](#ckeditor5/latest/features/pasting/paste-from-office.html) 

<a id="ckeditor5/latest/features/feature-digest.html--enhanced-paste-from-office">

#### Enhanced paste from Office

The Enhanced Paste from Word/Excel feature accurately retains formatting and structure when content is pasted from Microsoft Word documents into the editor. This includes preserving text styles, lists, tables, and layouts. The feature facilitates the transfer of documents from Word to CKEditor 5 without compromising on formatting.

[Feature page](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) 

<a id="ckeditor5/latest/features/feature-digest.html--paste-plain-text">

#### Paste plain text

The Paste as Plain Text feature strips formatting from the pasted text. This feature ensures that text pasted into the document adopts the style of the surrounding content, effectively described as “pasting without formatting.” Additionally, it intelligently converts double-line breaks into paragraphs and single-line breaks into soft breaks, aiding in maintaining the structural integrity of the document.

[Feature page](#ckeditor5/latest/features/pasting/paste-plain-text.html) 

<a id="ckeditor5/latest/features/feature-digest.html--slash-commands">

#### Slash commands

The Slash Commands feature lets users insert block elements and apply styles using just the keyboard. By pressing the / key, a panel with suggested commands appears, enabling quick and mouse-free actions. Users can filter through these commands by typing additional phrases after the /, making it easier to find specific commands. Additionally, the option to customize personal commands is available, allowing for a tailored editing experience.

[Feature page](#ckeditor5/latest/features/slash-commands.html) 

<a id="ckeditor5/latest/features/feature-digest.html--special-characters">

#### Special characters

The Special Characters feature lets you insert a variety of unique symbols and characters into your document. This includes mathematical operators, currency symbols, punctuation, graphic symbols like arrows or bullets, and Unicode letters that are not typically available on standard keyboards, such as umlauts or diacritics. Additionally, the feature supports the insertion of emojis. This tool is particularly useful for enhancing the detail and accuracy of content that requires specialized symbols.

[Feature page](#ckeditor5/latest/features/special-characters.html) 

<a id="ckeditor5/latest/features/feature-digest.html--templates">

#### Templates

The Templates feature enables the insertion of predefined content structures into documents, ranging from small content pieces, like formatted tables, to complete document frameworks, like formal letter templates. Templates accelerate the document creation process while ensuring adherence to the company’s content and document policies.

[Feature page](#ckeditor5/latest/features/template.html) 

<a id="ckeditor5/latest/features/feature-digest.html--configurations">

### Configurations

Configure CKEditor 5 to your liking. Choose the editor type, modify the toolbar, and select a language from our translated language packs.

<a id="ckeditor5/latest/features/feature-digest.html--editor-placeholder">

#### Editor placeholder

You can prompt the user to input content by displaying a configurable placeholder text when the editor is empty. This works similarly to the native DOM placeholder attribute used by inputs. Not to be confused with content placeholder.

[Feature page](#ckeditor5/latest/features/editor-placeholder.html) 

<a id="ckeditor5/latest/features/feature-digest.html--editor-ui-types">

#### Editor UI types

The editor’s user interface is dependent on the editor types. The editor provides functionality through specialized features accessible via a configurable toolbar or keyboard shortcuts. Some of these features are only available with certain editor types.

<a id="ckeditor5/latest/features/feature-digest.html--email-editing">

#### Email editing

CKEditor 5 provides a wide variety of tools and functions for editing almost any kind of content. This includes a wide array of tools and solutions to make email editing easier and more compatible with various email clients.

<a id="ckeditor5/latest/features/feature-digest.html--professionally-translated-language-packs">

#### Professionally translated language packs

CKEditor 5 provides 38 professionally translated language options, along with additional languages provided by community translations. CKEditor 5 also supports right-to-left (RTL) languages natively. When an RTL language is selected, the editor automatically adjusts its interface, including elements like toolbars, dropdowns, and buttons, to ensure an optimal editing experience.

[Feature page](#ckeditor5/latest/getting-started/setup/ui-language.html) 

<a id="ckeditor5/latest/features/feature-digest.html--toolbar-and-menus">

#### Toolbar and menus

The Toolbar Configuration feature provides different toolbar interfaces for editing content. The default toolbar includes dropdown menus and buttons for various editing functions. The Balloon Toolbar appears when text is selected, showing relevant tools. The Block Toolbar is accessed by clicking a button on the left-hand side of the editor, providing tools for the active block of content. Additionally, the Multiline Toolbar option allows for the expansion of the standard toolbar over multiple lines to display more tools simultaneously.

<a id="ckeditor5/latest/features/feature-digest.html--watchdog">

#### Watchdog

The watchdog utility protects you from data loss in case the editor crashes. It saves your content just before the crash and creates a new instance of the editor with your content intact.

[Feature page](#ckeditor5/latest/features/watchdog.html) 

<a id="ckeditor5/latest/features/feature-digest.html--compliance">

### Compliance

Make your content accessible to any person or restrict it to specific users.

<a id="ckeditor5/latest/features/feature-digest.html--accessibility-support">

#### Accessibility support

CKEditor 5 includes accessibility functionality designed to ensure content is accessible to all users. These features encompass keyboard navigation for easier content access without a mouse, screen reader compatibility facilitated by ARIA attributes, and semantic output markup for clearer interpretation of content structures. CKEditor 5 meets the requirements of the Web Content Accessibility Guidelines (WCAG) 2.2 at levels A and AA, as well as Section 508 of the Rehabilitation Act, as detailed in the Accessibility Conformance Report, ensuring broad accessibility compliance.

[Feature page](#ckeditor5/latest/features/accessibility.html) 

<a id="ckeditor5/latest/features/feature-digest.html--read-only-support">

#### Read-only support

The Read-Only Mode feature enables content to be locked from editing while still allowing it to be viewed. This mode is often used for restricting editing access based on user roles, allowing only specific users or groups to view the content without being able to modify it. Common uses include viewing sensitive documents like financial reports, software logs, or copyrighted stories that should not be altered but need to be accessible for copying or by screen readers. This mode can be toggled on and off by system triggers.

[Feature page](#ckeditor5/latest/features/read-only.html) 

<a id="ckeditor5/latest/features/feature-digest.html--restricted-editing">

#### Restricted editing

The Restricted Editing feature allows some sections of a document to be designated as non-editable while others remain editable. This feature supports two modes: the standard editing mode, where all content can be edited, and the restricted editing mode, where users can only modify parts of the content that are specifically marked as editable. This functionality is useful for workflows where one group of users creates document templates that include protected sections, and a second group fills in editable details such as names, dates, or product names without altering the rest of the document.

[Feature page](#ckeditor5/latest/features/restricted-editing.html) 

<a id="ckeditor5/latest/features/feature-digest.html--text-part-language">

#### Text Part Language

The Text Part Language feature allows users to specify the language of individual sections of text. This capability helps in creating documents that include multiple languages by ensuring that browsers and screen readers correctly interpret each part according to its designated language. This feature is particularly valuable for content that contains text in varying directions, such as an English document with Arabic citations. It supports the WCAG 3.1.2 Language of Parts specification, facilitating the creation of more accessible and comprehensible multilingual content.

[Feature page](#ckeditor5/latest/features/language.html) 

<a id="ckeditor5/latest/features/feature-digest.html--word-and-character-counter">

#### Word and character counter

The Word and Character Count feature provides a real-time tracking tool for monitoring the number of words and characters within the editor. This functionality assists in managing content length and ensuring it meets specific requirements or limits.

[Feature page](#ckeditor5/latest/features/word-count.html) 

<a id="ckeditor5/latest/features/feature-digest.html--wproofreader">

#### WProofreader

The Spelling and Grammar Checker is a proofreading tool that supports over 80 languages and dialects. It checks spelling and grammar in real time and through a separate dialog. Features include spelling autocorrect, text autocomplete, and suggestions that appear on hover. Users can create custom dictionaries for specific terms related to their brand or company. The tool is compliant with WCAG 2.1 and Section 508 accessibility standards. It also detects sentence-level errors and offers context-based correction suggestions.

[Feature page](#ckeditor5/latest/features/spelling-and-grammar-checking.html) 

<a id="ckeditor5/latest/features/feature-digest.html--customization">

### Customization

Customize your editor even further. Use components and helpers from our UI library to create a UI that will match your design system.

<a id="ckeditor5/latest/features/feature-digest.html--editor-sdk">

#### Editor SDK

Select from numerous toolbar styles and over 100 plugins to tailor an editor that perfectly fits your requirements, all without needing any development expertise. For those looking to go further, the CKEditor API enables the creation of custom plugins or modification of the editor’s functionality. To assist the development process, dedicated resources such as a package generator and the CKEditor 5 Inspector - a comprehensive suite of debugging tools - are provided, helping accelerate development work.

<a id="ckeditor5/latest/features/feature-digest.html--themes">

#### Themes

Customize the editor theme to match your design needs.

[Feature page](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) 

<a id="ckeditor5/latest/features/feature-digest.html--ui-library">

#### UI Library

The standard UI library of CKEditor 5 is @ckeditor/ckeditor5-ui. It provides base classes and helpers that allow for building a modular UI that seamlessly integrates with other components of the ecosystem.

[Feature page](#ckeditor5/latest/framework/architecture/ui-library.html) 

<a id="ckeditor5/latest/features/feature-digest.html--file-management">

### File management

Upload and manage your files using file management features. Take advantage of CKBox, our file management solution, or create your own using an adapter.

<a id="ckeditor5/latest/features/feature-digest.html--base64-upload-adapter">

#### Base64 Upload Adapter

Convert inserted images into Base64-encoded strings in the editor output. Images are stored with other content in the database without server-side processing.

[Feature page](#ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html) 

<a id="ckeditor5/latest/features/feature-digest.html--ckbox">

#### CKBox

Securely upload, store, edit, and utilize your images and files in CKEditor 5\. Simplify media discovery in your uploads with the media browser alongside an intuitive Image Editor for image adjustments. Designed to facilitate organization, CKBox enables integrations, maintains permissions, and uses Workspaces to categorize files according to the user, document, or customer. It guarantees fast loading and optimal display of your images across devices through an efficient CDN. Deployable on-premises or as cloud SaaS.

[Feature page](#ckeditor5/latest/features/file-management/ckbox.html) 

<a id="ckeditor5/latest/features/feature-digest.html--ckfinder">

#### CKFinder

The CKFinder feature lets you insert images and links to files into your content. CKFinder is a powerful file manager with various image editing and image upload options.

[Feature page](#ckeditor5/latest/features/file-management/ckfinder.html) 

<a id="ckeditor5/latest/features/feature-digest.html--custom-upload-adapter">

#### Custom Upload Adapter

Have your own file management solution? Use this adapter to integrate your preferred software with CKEditor.

[Feature page](#ckeditor5/latest/features/images/image-upload/custom-upload-adapter.html) 

<a id="ckeditor5/latest/features/feature-digest.html--simple-upload-adapter">

#### Simple Upload Adapter

Upload images to your server using the XMLHttpRequest API with a minimal editor configuration.

[Feature page](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html) 

<a id="ckeditor5/latest/features/feature-digest.html--uploadcare">

#### Uploadcare

Upload, store, transform, optimize, and deliver images, videos, and documents with this cloud-based file handler. Upload media from local storage, web cameras, cloud services, and social networks with automated media optimization through a CDN for responsive image delivery. Popular features include adaptive image quality, automated image format conversion, progressive JPEG, and options for preview, resize, stretch, crop, content-aware crop, and setting fill color.

[Feature page](https://uploadcare.com/)

<a id="ckeditor5/latest/features/file-management/ckbox.html">source file: "ckeditor5/latest/features/file-management/ckbox.html"</a>

## CKBox file manager

CKBox is a dedicated asset manager and management platform service that provides a comprehensive digital asset management experience for CKEditor 5.

It handles file uploads and significantly reduces the effort required to build a complete modern editing solution that supports optimized and [responsive images](#ckeditor5/latest/features/images/images-responsive.html). Functionally, CKBox replaces the basic CKEditor 5 image upload feature by integrating a comprehensive file manager.

<a id="ckeditor5/latest/features/file-management/ckbox.html--demo">

### Demo

<a id="ckeditor5/latest/features/file-management/ckfinder.html">source file: "ckeditor5/latest/features/file-management/ckfinder.html"</a>

## CKFinder file manager

The CKFinder feature lets you insert images and links to files into your content. CKFinder is a powerful file manager with various image editing and image upload options.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--demos">

### Demos

<a id="ckeditor5/latest/features/file-management/ckfinder.html--image-upload-only">

#### Image upload only

This demo shows the integration where the file manager’s server connector handles [image upload](#ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-image-upload-only) only:

* Paste an image directly into the editor. It will be automatically uploaded using the server-side connector.
* Use the insert image button  in the toolbar to insert an image.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--full-integration">

#### Full integration

This demo shows the [full integration](#ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-full-integration) with the CKFinder file uploader:

* Paste an image directly into the editor. It will be automatically uploaded using the server-side connector.
* Use the insert image or file button  in the toolbar to open the CKFinder file manager. Then insert an image or a link to any other file.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--additional-feature-information">

### Additional feature information

The CKFinder integration feature is a bridge between the CKEditor 5 WYSIWYG editor and the [CKFinder](https://ckeditor.com/ckfinder) file manager and uploader. CKFinder is a commercial application designed with CKEditor compatibility in mind. It is available as version 3.x for PHP, ASP.NET, and Java and version 2.x for ASP and ColdFusion.

You can use this feature in the rich-text editor in two different ways:

* [**As a server-side connector only**](#ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-image-upload-only) ([demo](#ckeditor5/latest/features/file-management/ckfinder.html--image-upload-only)). In this scenario, images dropped or pasted into the editor are uploaded to the CKFinder server-side connector running on your server.
* [**As a server and client-side file manager integration**](#ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-full-integration) ([demo](#ckeditor5/latest/features/file-management/ckfinder.html--full-integration)). Images dropped or pasted directly into the editor are uploaded to the server (just like in the first option).  
There are more cool features available, for instance:

  * **Uploading** using the full user interface.
  * Uploading **multiple files** at once.
  * **Browsing** previously uploaded images.
  * **Editing** images (cropping, resizing, etc.).
  * **Organizing** or deleting images.  
Check out the [CKFinder file manager website](https://ckeditor.com/ckfinder/) to learn more about the features you can use in your project.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/file-management/ckfinder.html--from-npm">

#### From npm

```
import { ClassicEditor, CKFinder, CKFinderUploadAdapter } from 'ckeditor5';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ CKFinder, CKFinderUploadAdapter, /* ... */ ],
        toolbar: [ 'ckfinder', 'uploadImage', /* ... */ ], // Depending on your preference.
        ckfinder: {
            // Configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/file-management/ckfinder.html--from-cdn">

#### From CDN

```
const { ClassicEditor, CKFinder: CKFinderPlugin, CKFinderUploadAdapter } = CKEDITOR;

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ CKFinderPlugin, CKFinderUploadAdapter, /* ... */ ],
        toolbar: [ 'ckfinder', 'uploadImage', /* ... */ ], // Depending on your preference.
        ckfinder: {
            // Configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/file-management/ckfinder.html--configuration">

### Configuration

The feature is configurable by using the [config.ckfinder](../../api/module%5Fckfinder%5Fckfinderconfig-CKFinderConfig.html) object.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-image-upload-only">

#### Configuring the image upload only

This feature can upload images automatically to the server (for example, when the user drops an image into the content) thanks to the [CKFinder upload adapter](../../api/module%5Fadapter-ckfinder%5Fuploadadapter-CKFinderUploadAdapter.html). All it requires is the correct [config.ckfinder.uploadUrl](../../api/module%5Fckfinder%5Fckfinderconfig-CKFinderConfig.html#member-uploadUrl) path.

Assuming that you [installed the CKFinder PHP server-side connector](https://ckeditor.com/docs/ckfinder/ckfinder3-php/quickstart.html#quickstart%5Finstallation%5Ffolders) (and it is available under `https://example.com/ckfinder/`), use the following [quick upload](https://ckeditor.com/docs/ckfinder/ckfinder3-php/commands.html#command%5Fquick%5Fupload) command URL to enable the image upload:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ckfinder: {
            // Upload the images to the server using the CKFinder QuickUpload command.
            uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json'
            }
        } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

See the **[demo of the image upload only](#ckeditor5/latest/features/file-management/ckfinder.html--image-upload-only)**.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-full-integration">

#### Configuring the full integration

To use both the image upload functionality and the file manager user interface in your application, you must first load the CKFinder JavaScript library. Then enable the CKFinder integration in your rich-text editor instance.

The easiest way to load the CKFinder library is to include the `<script>` tag loading the `ckfinder.js` file first:

```
<script src="https://example.com/ckfinder/ckfinder.js"></script>

```

Then:

* Make sure that the [CKFinder plugin](../../api/module%5Fckfinder%5Fckfinder-CKFinder.html) for CKEditor 5 is enabled. See the [Installation](#ckeditor5/latest/features/file-management/ckfinder.html--installation) section.
* To enable the automatic file upload to the server when an image is pasted or dropped into the editor content, set the correct [config.ckfinder.uploadUrl](../../api/module%5Fckfinder%5Fckfinderconfig-CKFinderConfig.html#member-uploadUrl) path.
* To display the toolbar button that opens the CKFinder file manager UI allowing the users to choose the files on the server, make sure that `'ckfinder'` is present in your [config.toolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).
* Additionally, you can use [config.ckfinder.options](../../api/module%5Fckfinder%5Fckfinderconfig-CKFinderConfig.html#member-options) to define [CKFinder’s options](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config). For example:  
  * You can define [options.resourceType](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config-cfg-resourceType) to tell CKFinder the specified resource type can be browsed when the user clicks the button.
  * You can define [options.language](https://ckeditor.com/docs/ckfinder/ckfinder3/#!/api/CKFinder.Config-cfg-language) to set the UI language of CKFinder. By default, it will be set to the UI language of the editor.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ckfinder: {
            // Upload the images to the server using the CKFinder QuickUpload command.
            uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json',

            // Define the CKFinder configuration (if necessary).
            options: {
                resourceType: 'Images'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

See the **[demo of the full integration](#ckeditor5/latest/features/file-management/ckfinder.html--full-integration)**.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--configuring-the-opener">

##### Configuring the opener

You can change the way CKFinder opens using the [config.ckfinder.openerMethod](../../api/module%5Fckfinder%5Fckfinderconfig-CKFinderConfig.html#member-openerMethod) option.

By default, the file manager opens as a modal. To open it in a new pop-up window, set the configuration value to `popup`:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        ckfinder: {
            // Open the file manager in the pop-up window.
            openerMethod: 'popup'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/file-management/ckfinder.html--configuring-allowed-file-types">

#### Configuring allowed file types

You should configure the allowed file types that can be uploaded in two places:

* On the client side, in CKEditor 5, restricting image upload through the CKEditor 5 UI and commands
* On the server side, in CKFinder, restricting the file formats accepted in CKFinder

<a id="ckeditor5/latest/features/file-management/ckfinder.html--client-side-configuration">

##### Client-side configuration

Use the [image.upload.types](../../api/module%5Fimage%5Fimageconfig-ImageUploadConfig.html#member-types) configuration option to define the allowed image MIME types that the users can upload to CKEditor 5.

By default, users can upload `jpeg`, `png`, `gif`, `bmp`, `webp`, and `tiff` files, but you can customize this behavior to accept, for example, SVG files.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--server-side-configuration">

##### Server-side configuration

Use the `allowedExtensions` configuration option to define the file extension allowed to be uploaded with CKFinder for a particular resource type. Refer to the [relevant server-side connector documentation](#ckfinder/latest/index.html) to learn more.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--common-api">

### Common API

The [CKFinder](../../api/module%5Fckfinder%5Fckfinder-CKFinder.html) plugin registers:

* The `'ckfinder'` UI button component.
* The `'ckfinder'` command implemented by the [CKFinderCommand](../../api/module%5Fckfinder%5Fckfindercommand-CKFinderCommand.html).  
You can open CKFinder by executing the following code:  
```  
editor.execute( 'ckfinder' );  
```

Additionally, in the “image upload only” integration, you can use the following button and command registered by the [ImageUpload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin:

* The `'uploadImage'` UI button component.
* The `'uploadImage'` command implemented by the [UploadImageCommand](../../api/module%5Fimage%5Fimageupload%5Fuploadimagecommand-UploadImageCommand.html).

<a id="ckeditor5/latest/features/file-management/ckfinder.html--whats-next">

### What’s next

Check out the comprehensive [Image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) to learn more about different ways of uploading images in CKEditor 5.

See the [image feature guide](#ckeditor5/latest/features/images/images-overview.html) to find out more about handling images in CKEditor 5.

<a id="ckeditor5/latest/features/file-management/ckfinder.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ckfinder>.

<a id="ckeditor5/latest/features/file-management/uploadcare.html">source file: "ckeditor5/latest/features/file-management/uploadcare.html"</a>

## Uploadcare image uploader and editor

Uploadcare is a dedicated image manager supporting image upload and editing. The Uploadcare feature lets you easily upload images from various services like Dropbox, Facebook, Google Drive, Google Photos, or OneDrive and insert them into your content. It offers an image editor with multiple editing options, optimization capabilities and provides a [responsive images mechanism](#ckeditor5/latest/features/images/images-responsive.html) for CKEditor 5.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--how-uploadcare-enhances-ckeditor-5">

### How Uploadcare enhances CKEditor 5

As a full-fledged image uploader and editor, Uploadcare also replaces the basic CKEditor 5 image upload feature. It provides image upload and editing capabilities:

* Enables images upload directly from services like Dropbox, Facebook, Google Drive, Google Photos, OneDrive.
* Enables images upload from local machine and directly via external URL.
* Enables drag & drop uploads of images.
* Transforms the _Image_ toolbar button, allowing the user to quickly upload and insert images.
* Adds a separate dedicated image toolbar button to quickly open image editor for selected image.
* Provides image editing capabilities like crop, resize, rotate, flip, apply filters, and adjust image parameters (like contrast, brightness, saturation).
* Uploadcare storage is powered by AWS S3 and you can use your own bucket.

With Uploadcare you no longer need to write a server-side code to upload and edit images.

To find out more about Uploadcare, visit the [Uploadcare website](https://uploadcare.com/).

<a id="ckeditor5/latest/features/file-management/uploadcare.html--demo">

### Demo

To upload a file using Uploadcare, use the upload image toolbar button  and choose the provider you want to upload from. You can choose more than one file at a time. Use the edit image button  from the image contextual toolbar to edit the selected image.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

Image files are inserted into the content as images that you can drag around and resize.

You can also upload images by dragging them into your content. After you drag an image into the editor, it gets uploaded into the Uploadcare cloud storage and inserted into the content.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration.

The Uploadcare upload feature requires following image plugins to work correctly:

* [The Image feature](../../api/module%5Fimage%5Fimage-Image.html),
* [The ImageUpload feature](../../api/module%5Fimage%5Fimageupload-ImageUpload.html),
* [The ImageInsert feature](../../api/module%5Fimage%5Fimageinsert-ImageInsert.html),
* [The PictureEditing feature](../../api/module%5Fimage%5Fpictureediting-PictureEditing.html).

Make sure to include them during editor setup:

Further in the document, the dependency plugins will be omitted in code listings for clarity.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--adding-image-editing-capabilities">

#### Adding image editing capabilities

To add image editor allowing to invoke it straight from the image contextual toolbar (available when an image is selected), the `UploadcareImageEdit` plugins needs to be loaded and added to the toolbar configuration.

Further in the document, the dependency plugins will be omitted in code listings for clarity.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

After you purchase a license, log into your Uploadcare customer dashboard to create a public API key, as explained in the [Uploadcare Project settings guide](https://uploadcare.com/docs/start/settings/#keys-public).

<a id="ckeditor5/latest/features/file-management/uploadcare.html--configuration">

### Configuration

The feature can be configured via the [config.uploadcare](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareConfig.html) object.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--choosing-services-to-upload-from">

#### Choosing services to upload from

Uploadcare feature allows uploading images from multiple external services - Dropbox, Facebook, Google Drive, Google Photos, OneDrive, and from local machine and external URLs. The list of allowed upload methods is configurable via [config.uploadcare.uploader.sourceList](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareUploaderConfig.html#member-sourceList).

Available options are:

* `dropbox`
* `facebook`
* `gdrive`
* `gphotos`
* `onedrive`
* `local`
* `url`

For example, to allow users to upload images from local computer, Dropbox and OneDrive, the configuration would look as below:

```
ClassicEditor
    .create( {
        uploadcare: {
            uploader: {
                sourceList: [
                    'local',
                    'dropbox',
                    'onedrive'
                ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/file-management/uploadcare.html--editing-external-images">

#### Editing external images

To enable Uploadcare to edit external images (not hosted by the Uploadcare service) you need to whitelist the URLs of the images. You can do this using the [config.uploadcare.allowExternalImagesEditing](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareConfig.html#member-allowExternalImagesEditing) option:

```
ClassicEditor
    .create( {
        uploadcare: {
            allowExternalImagesEditing: [ 'origin', /^cksource.com/ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The image is editable if this option is:

* a regular expression and it matches the image URL, or
* a custom function that returns true for the image URL, or
* `origin` literal and the image URL is from the same origin, or
* an array of the above and the image URL matches one of the array elements.

<a id="ckeditor5/latest/features/file-management/uploadcare.html--adjusting-other-configuration-options">

#### Adjusting other configuration options

Uploadcare feature configuration directly exposes other Uploadcare configuration options, and those can be set via CKEditor 5 configuration directly. Please refer to official Uploadcare documentation to get familiar with all configuration options.

The configuration related to upload process should be set via [config.uploadcare.uploader](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareConfig.html#member-uploader) object:

```
ClassicEditor
    .create( {
        uploadcare: {
            uploader: {
                cropPreset: '1:1',
                imageShrink: '800x600'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Please see all available options in [the official Uploadcare documentation](https://uploadcare.com/docs/file-uploader/options/).

The configuration related to image editor should be set via [config.uploadcare.editor](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareConfig.html#member-editor) object:

```
ClassicEditor
    .create( {
        uploadcare: {
            editor: {
                cropPreset: '5:4'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Please see all available options in [the official Uploadcare documentation](https://uploadcare.com/docs/file-uploader/image-editor/#configuration).

<a id="ckeditor5/latest/features/file-management/uploadcare.html--locale-configuration">

#### Locale configuration

Since the Uploadcare integration plugin bases on an external component, it is necessary to make an extra step to provide translations for the Uploadcare component.

You can provide the translations using the [config.uploadcare.locale](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareConfig.html#member-locale) option.

The plugin automatically uses the editor’s language (`editor.locale.contentLanguage`) as the locale name. If the editor language is different from `'en'`, you need to provide translations for that language (see the examples below). The `locale` property is used only to supply translations that will be used by Uploadcare components.

For information on how to configure the editor’s language, see the [CKEditor 5 localization documentation](#ckeditor5/latest/framework/deep-dive/ui/localization.html).

<a id="ckeditor5/latest/features/file-management/uploadcare.html--using-cdn-translations">

##### Using CDN translations

Load pre-defined translations from Uploadcare CDN:

```
// Dynamic import
ClassicEditor
    .create( {
        uploadcare: {
            pubkey: 'YOUR_UPLOADCARE_KEY',
            locale: () => import( 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/locales/file-uploader/de.js' )
                .then( module => module.default )
        }
    } );

// Or static import
import deLocale from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/locales/file-uploader/de.js';

ClassicEditor
    .create( {
        uploadcare: {
            pubkey: 'YOUR_UPLOADCARE_KEY',
            locale: deLocale
        }
    } );

```

<a id="ckeditor5/latest/features/file-management/uploadcare.html--using-custom-translations">

##### Using custom translations

Provide your own translation object:

```
ClassicEditor
    .create( {
        uploadcare: {
            pubkey: 'YOUR_UPLOADCARE_KEY',
            locale: {
                'locale-id': 'de',
                'social-source-lang': 'de',
                'upload-file': 'Datei hochladen',
                'file__one': 'Datei',
                'file__other': 'Dateien',
                'header-uploading': 'Lade {{count}} {{plural:file(count)}} hoch',
                // More translations.
            }
        }
    } );

```

<a id="ckeditor5/latest/features/file-management/uploadcare.html--common-api">

### Common API

The [Uploadcare](../../api/module%5Fuploadcare%5Fuploadcare-Uploadcare.html) plugin registers:

* The `'uploadcare'` UI button component for uploading images.
* The `'uploadcare'` command implemented by the [UploadcareCommand](../../api/module%5Fuploadcare%5Fuploadcarecommand-UploadcareCommand.html).

You can open Uploadcare upload dialog by executing the following code:

```
editor.execute( 'uploadcare' );

```

If you want to use the Uploadcare editing capabilities straight from the editor, the [UploadcareImageEdit](../../api/module%5Fuploadcare%5Fuploadcareimageedit-UploadcareImageEdit.html) plugin will register the following:

* The `'uploadcareImageEdit'` UI button component in the Image toolbar for the uploadcare image editor.
* The `'uploadcareImageEdit'` command implemented by the [UploadcareImageEdit](../../api/module%5Fuploadcare%5Fuploadcareimageedit-UploadcareImageEdit.html).

You can open Uploadcare image edit dialog by executing the following code:

```
editor.execute( 'uploadcareImageEdit' );

```

<a id="ckeditor5/latest/features/file-management/uploadcare.html--whats-next">

### What’s next

Be sure to check out the comprehensive [Image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) guide to learn more about different ways of uploading images in CKEditor 5.

See the [image feature](#ckeditor5/latest/features/images/images-overview.html) guide to find out more about handling images in CKEditor 5 in general.

<a id="ckeditor5/latest/features/find-and-replace.html">source file: "ckeditor5/latest/features/find-and-replace.html"</a>

## Find and replace

The find and replace feature lets you find and replace any text in your document. This speeds up your work and helps with the consistency of your content.

<a id="ckeditor5/latest/features/find-and-replace.html--demo">

### Demo

Use the find and replace toolbar button  to open the search dialog. Use it to find and replace words or phrases. You can also use the Ctrl/Cmd+F keyboard shortcut. Try replacing “AI” with “artificial intelligence” to make the content appeal to less tech-savvy users. Be careful to match the case!

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/find-and-replace.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/find-and-replace.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/find-and-replace.html--configuring-the-ui-type">

#### Configuring the UI type

By default, the find and replace form displays inside a dialog. That allows for keeping it open while editing the document at the same time. Alternatively, you can display the feature in a dropdown. To do this, use the [config.findAndReplace.uiType](../api/module%5Ffind-and-replace%5Ffindandreplaceconfig-FindAndReplaceConfig.html) configuration option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        findAndReplace: {
            uiType: 'dropdown'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/find-and-replace.html--related-features">

### Related features

* [Automatic text transformation](#ckeditor5/latest/features/text-transformation.html) – Enables automatic turning of snippets such as `(tm)` into `™` and `"foo"` into `“foo”`.

<a id="ckeditor5/latest/features/find-and-replace.html--common-api">

### Common API

The [FindAndReplace](../api/module%5Ffind-and-replace%5Ffindandreplace-FindAndReplace.html) plugin registers the `'findAndReplace'` UI button component and the ['find'](../api/module%5Ffind-and-replace%5Ffindcommand-FindCommand.html), ['findNext'](../api/module%5Ffind-and-replace%5Ffindnextcommand-FindNextCommand.html), ['findPrevious'](../api/module%5Ffind-and-replace%5Ffindpreviouscommand-FindPreviousCommand.html), ['replace'](../api/module%5Ffind-and-replace%5Freplacecommand-ReplaceCommand.html) and ['replaceAll'](../api/module%5Ffind-and-replace%5Freplaceallcommand-ReplaceAllCommand.html) commands.

You can execute the commands using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Find all occurrences of a given text.
editor.execute( 'find', 'steam' );

```

You can also move the highlight through all matched results with the ['findNext'](../api/module%5Ffind-and-replace%5Ffindnextcommand-FindNextCommand.html) and ['findPrevious'](../api/module%5Ffind-and-replace%5Ffindpreviouscommand-FindPreviousCommand.html) commands:

```
// Move the search highlight to the next match.
editor.execute( 'findNext' );

```

You can also replace all occurrences of a given text in the editor instance using the ['replaceAll'](../api/module%5Ffind-and-replace%5Freplaceallcommand-ReplaceAllCommand.html) command:

```
editor.execute( 'replaceAll', 'diesel', 'steam' );

```

<a id="ckeditor5/latest/features/find-and-replace.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-find-and-replace>.

<a id="ckeditor5/latest/features/font.html">source file: "ckeditor5/latest/features/font.html"</a>

## Font family, size, and color

The font feature lets you change font family, size, and color (including background color).

<a id="ckeditor5/latest/features/font.html--demo">

### Demo

Use the toolbar dropdowns in the demo below to control the font size  and font family . You can also change both the font color  and the font background color  with predefined palette or color picker .

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/font.html--additional-feature-information">

### Additional feature information

The font styles, just like the [basic text styles](#ckeditor5/latest/features/basic-styles.html), can serve many purposes. You can apply the font size setting globally or to a selected part of the text to make it catch the eye of the reader. Using different font families can help differentiate between sections of the content that serve various purposes (like main text and a side quotation or a recap). Different font colors can work as markers and guides just like font background colors that stand out even more and draw attention.

The plugin enables the following features in the rich-text editor:

* [FontFamily](../api/module%5Ffont%5Ffontfamily-FontFamily.html) – Change the font family by applying inline `<span>` elements with a `font-family` in the `style` attribute.
* [FontSize](../api/module%5Ffont%5Ffontsize-FontSize.html) – Control the font size by applying inline `<span>` elements that either have a CSS class or a `font-size` in the `style` attribute.
* [FontColor](../api/module%5Ffont%5Ffontcolor-FontColor.html) – Control the font color by applying inline `<span>` elements with a `color` in the `style` attribute.
* [FontBackgroundColor](../api/module%5Ffont%5Ffontbackgroundcolor-FontBackgroundColor.html) – Control the font background color by applying inline `<span>` elements with a `background-color` in the `style` attribute.

<a id="ckeditor5/latest/features/font.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

You can also add just one or a selected few of the font features to your plugin list and the toolbar configuration:

<a id="ckeditor5/latest/features/font.html--configuring-the-font-family-feature">

### Configuring the font family feature

You can configure which font family options are supported by the WYSIWYG editor. Use the [config.fontFamily.options](../api/module%5Ffont%5Ffontconfig-FontFamilyConfig.html#member-options) configuration option to do so.

Use the special `'default'` keyword to use the default font family defined in the web page styles. It removes any custom font family.

For example, the following editor supports two font families besides the default one:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontFamily: {
            options: [
                'default',
                'Ubuntu, Arial, sans-serif',
                'Ubuntu Mono, Courier New, Courier, monospace'
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontFamily', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--accepting-all-font-names">

#### Accepting all font names

By default, all `font-family` values that are not specified in the `config.fontFamily.options` are stripped. You can enable support for all font names by using the [config.fontFamily.supportAllValues](../api/module%5Ffont%5Ffontconfig-FontFamilyConfig.html#member-supportAllValues) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontFamily: {
            options: [
                // Font family configuration options are described in the "Configuring the font family feature" section.
                // ...
            ],
            supportAllValues: true
        },
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--configuring-the-font-size-feature">

### Configuring the font size feature

It is possible to configure which font size options are supported by the WYSIWYG editor. Use the [config.fontSize.options](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-options) configuration option to do so.

Use the special `'default'` keyword to use the default font size defined in the web page styles. It removes any custom font size.

The font size feature supports two ways of defining the configuration: using predefined (named) presets or simple numeric values.

<a id="ckeditor5/latest/features/font.html--using-the-predefined-presets">

#### Using the predefined presets

The font size feature defines 4 named presets:

* `'tiny'`
* `'small'`
* `'big'`
* `'huge'`

Each size is represented in the view as a `<span>` element with the `text-*` class. For example, the `'tiny'` preset looks as follows in the editor data:

```
<span class="text-tiny">...</span>

```

The CSS definition for the classes (presets) must be included in the web page styles where the edited content is rendered.

Here is an example of the font size CSS classes:

```
.ck-content .text-tiny {
    font-size: 0.7em;
}

.ck-content .text-small {
    font-size: 0.85em;
}

.ck-content .text-big {
    font-size: 1.4em;
}

.ck-content .text-huge {
    font-size: 1.8em;
}

```

An example of an editor that supports two font sizes:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontSize: {
            options: [
                'tiny',
                'default',
                'big'
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontSize', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--using-numerical-values">

#### Using numerical values

The font size feature also supports numerical values.

In this case, each size is represented in the view as a `<span>` element with the `font-size` style set in `px`. For example, `14` will be represented in the editor data as:

```
<span style="font-size: 14px">...</span>

```

Here is an example of the WYSIWYG editor that supports numerical font sizes. Note that `'default'` is controlled by the default styles of the web page:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontSize: {
            options: [
                9,
                11,
                13,
                'default',
                17,
                19,
                21
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontSize', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--accepting-all-font-sizes">

#### Accepting all font sizes

By default, all `font-size` values that are not specified in the `config.fontSize.options` are stripped. You can enable support for all font sizes by using the [config.fontSize.supportAllValues](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-supportAllValues) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontSize: {
            options: [
                // Numerical values.
                // ...
            ],
            supportAllValues: true
        },
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features">

### Configuring the font color and font background color features

Both font color and font background color features are configurable and share the same configuration format.

Check out the WYSIWYG editor below with both features customized using the editor configuration:

<a id="ckeditor5/latest/features/font.html--specifying-available-colors">

#### Specifying available colors

It is possible to configure which colors are available in the color dropdown. Use the [config.fontColor.colors](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-colors) and [config.fontBackgroundColor.colors](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-colors) configuration options to do so.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontColor: {
            colors: [
                {
                    color: 'hsl(0, 0%, 0%)',
                    label: 'Black'
                },
                {
                    color: 'hsl(0, 0%, 30%)',
                    label: 'Dim grey'
                },
                {
                    color: 'hsl(0, 0%, 60%)',
                    label: 'Grey'
                },
                {
                    color: 'hsl(0, 0%, 90%)',
                    label: 'Light grey'
                },
                {
                    color: 'hsl(0, 0%, 100%)',
                    label: 'White',
                    hasBorder: true
                },
                // More colors.
                // ...
            ]
        },
        fontBackgroundColor: {
            colors: [
                {
                    color: 'hsl(0, 75%, 60%)',
                    label: 'Red'
                },
                {
                    color: 'hsl(30, 75%, 60%)',
                    label: 'Orange'
                },
                {
                    color: 'hsl(60, 75%, 60%)',
                    label: 'Yellow'
                },
                {
                    color: 'hsl(90, 75%, 60%)',
                    label: 'Light green'
                },
                {
                    color: 'hsl(120, 75%, 60%)',
                    label: 'Green'
                },
                // More colors.
                // ...
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontColor', 'fontBackgroundColor', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--changing-the-geometry-of-the-color-grid">

#### Changing the geometry of the color grid

You can configure the number of columns in the color dropdown by setting the [config.fontColor.columns](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-columns) and [config.fontBackgroundColor.columns](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-columns) configuration options.

Usually, you will want to use this option when changing the number of [available colors](#ckeditor5/latest/features/font.html--specifying-available-colors).

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontColor: {
            colors: [
                // 9 colors defined here.
                // ...
            ]

            columns: 3, // So, you can display them in 3 columns.

            // Optional configuration of the number of document colors.
            // ...
        },
        fontBackgroundColor: {
            columns: 6,
            // Background color options.
            // ...
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontColor', 'fontBackgroundColor', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--documents-colors">

#### Documents colors

The font and font background color dropdowns contain the “Document colors” section. It lists the colors already used in the document for the users to be able to easily reuse them (for consistency purposes).

By default, the number of displayed document colors is limited to one row, but you can adjust it (or remove the whole section) by using the [config.fontColor.documentColors](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-documentColors) or [config.fontBackgroundColor.documentColors](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-documentColors) options.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontColor: {
            // Display 6 columns in the color grid.
            columns: 6,

            // And 12 document colors (2 rows of them).
            documentColors: 12,

            // Optional available font colors configuration.
            // ...
        },
        fontBackgroundColor: {
            // Remove the "Document colors" section.
            documentColors: 0,

            // Background color options.
            // ...
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontColor', 'fontBackgroundColor', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--color-picker">

#### Color picker

You can set colors from outside of the pre-configured palette using the “Color picker” option available at the bottom of the color selection dropdown.

Color picker applies colors in the **HSL** format as it is the default for the font color feature. You can change this using the [config.fontColor.colorPicker.format](../api/module%5Fui%5Fcolorpicker%5Futils-ColorPickerConfig.html) option. Available color formats are defined in the [ColorPickerOutputFormat](../api/module%5Fui%5Fcolorpicker%5Futils-ColorPickerOutputFormat.html) type. This change will not affect the color input – it always accepts only values given in the `hex` format (with or without the `#` sign at the beginning).

To turn off the color picker entirely for the given feature, set the [config.fontColor.colorPicker](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-colorPicker) (or [config.fontBackgroundColor.colorPicker](../api/module%5Ffont%5Ffontconfig-FontColorConfig.html#member-colorPicker)) option to `false`.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fontColor: {
            colorPicker: {
                // Use 'hex' format for output instead of 'hsl'.
                format: 'hex'
            }
        },
        fontBackgroundColor: {
            // Do not display the color picker.
            colorPicker: false
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'fontColor', 'fontBackgroundColor', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/font.html--email-client-color-format-compatibility">

#### Email client color format compatibility

When designing content for emails, it is important to be aware that many email clients have limited support for various color formats. For maximum compatibility in email templates, consider the following limitations:

<a id="ckeditor5/latest/features/font.html--unsupported-color-formats-in-most-email-clients">

##### Unsupported color formats in most email clients:

* hsl
* hsla
* hwb
* lab
* lch
* oklab
* oklch
* color-mix
* rgba

<a id="ckeditor5/latest/features/font.html--recommended-color-formats-for-email-compatibility">

##### Recommended color formats for email compatibility:

* Hexadecimal (for example, `#FF0000`)
* RGB (for example, `rgb(255, 0, 0)`)
* Named colors (for example, `red`)

Using these compatible formats will ensure your content displays consistently across different email clients.

<a id="ckeditor5/latest/features/font.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you format your content:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_, and others.
* [Styles](#ckeditor5/latest/features/style.html) – Apply pre-configured styles to existing elements in the editor content.
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Because it does matter whether the content is left, right, centered, or justified.
* [Case change](#ckeditor5/latest/features/case-change.html) – Turn a text fragment or block into uppercase, lowercase, or title case.
* [Headings](#ckeditor5/latest/features/headings.html) – Divide your content into sections.
* [Highlight](#ckeditor5/latest/features/highlight.html) – Mark important words and passages, aiding a review or drawing attention to specific parts of the content.
* [Format painter](#ckeditor5/latest/features/format-painter.html) – Easily copy text formatting and apply it in a different place in the edited document.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/font.html--common-api">

### Common API

The [FontFamily](../api/module%5Ffont%5Ffontfamily-FontFamily.html) plugin registers the following components:

* The `'fontFamily'` dropdown.
* The ['fontFamily'](../api/module%5Ffont%5Ffontfamily%5Ffontfamilycommand-FontFamilyCommand.html) command.  
The number of options and their names correspond to the [config.fontFamily.options](../api/module%5Ffont%5Ffontconfig-FontFamilyConfig.html#member-options) configuration option.  
You can change the font family of the current selection by executing the command with a desired value:  
```  
editor.execute( 'fontFamily', { value: 'Arial' } );  
```  
The `value` must correspond to the first font name in the configuration string. For the following default configuration:  
```  
fontFamily.options = [  
    'default',  
    'Arial, Helvetica, sans-serif',  
    'Courier New, Courier, monospace',  
    'Georgia, serif',  
    'Lucida Sans Unicode, Lucida Grande, sans-serif',  
    'Tahoma, Geneva, sans-serif',  
    'Times New Roman, Times, serif',  
    'Trebuchet MS, Helvetica, sans-serif',  
    'Verdana, Geneva, sans-serif'  
]  
```  
the `'fontFamily'` command will accept the corresponding strings as values:

  * `'Arial'`
  * `'Courier New'`
  * `'Georgia'`
  * `'Lucida Sans Unicode'`
  * `'Tahoma'`
  * `'Times New Roman'`
  * `'Trebuchet MS'`
  * `'Verdana'`  
Note that passing an empty value will remove the `fontFamily` attribute from the selection (`default`):  
```  
editor.execute( 'fontFamily' );  
```

The [FontSize](../api/module%5Ffont%5Ffontsize-FontSize.html) plugin registers the following components:

* The `'fontSize'` dropdown.
* The ['fontSize'](../api/module%5Ffont%5Ffontsize%5Ffontsizecommand-FontSizeCommand.html) command.  
The number of options and their names correspond to the [config.fontSize.options](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-options) configuration option.  
You can change the font size of the current selection by executing the command with a desired value:  
```  
// For numerical values:  
editor.execute( 'fontSize', { value: 10 } );  
// For named presets:  
editor.execute( 'fontSize', { value: 'small' } );  
```  
Passing an empty value will remove any `config.fontSize` set:  
```  
editor.execute( 'fontSize' );  
```

The [FontColor](../api/module%5Ffont%5Ffontcolor-FontColor.html) plugin registers the following components:

* The `'fontColor'` dropdown.
* The ['fontColor'](../api/module%5Ffont%5Ffontcolor%5Ffontcolorcommand-FontColorCommand.html) command.  
You can change the font color of the current selection by executing the command with a desired value:  
```  
editor.execute( 'fontColor', { value: 'rgb(30, 188, 97)' } );  
```  
Passing an empty value will remove the font color from the selection:  
```  
editor.execute( 'fontColor' );  
```

The [FontBackgroundColor](../api/module%5Ffont%5Ffontbackgroundcolor-FontBackgroundColor.html) plugin registers the following components:

* The `'fontBackgroundColor'` dropdown.
* The ['fontBackgroundColor'](../api/module%5Ffont%5Ffontbackgroundcolor%5Ffontbackgroundcolorcommand-FontBackgroundColorCommand.html) command.  
You can change the font background color of the current selection by executing the command with a desired value:  
```  
editor.execute( 'fontBackgroundColor', { value: 'rgb(30, 188, 97)' } );  
```  
Passing an empty value will remove the font background color from the selection:  
```  
editor.execute( 'fontBackgroundColor' );  
```

<a id="ckeditor5/latest/features/font.html--content-compatibility">

### Content compatibility

The [Font](../api/module%5Ffont%5Ffont-Font.html) plugin provides basic support for the deprecated `<font>` tag.

While `<font color>` is always supported, to use `<font face>` and `<font size>` you need to enable the [config.fontFamily.supportAllValues](../api/module%5Ffont%5Ffontconfig-FontFamilyConfig.html#member-supportAllValues) and [config.fontSize.supportAllValues](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-supportAllValues) options respectively.

Text formatted with `<font>` is accepted by the plugin, but the editor always returns the markup in a modern format, so the transformation is one way.

<a id="ckeditor5/latest/features/font.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-font>.

<a id="ckeditor5/latest/features/footnotes.html">source file: "ckeditor5/latest/features/footnotes.html"</a>

## Footnotes

The footnotes feature allows you to add supplementary information, citations, or explanatory notes that appear at the bottom of your document without cluttering the main text. Simply select any content you need annotated and click the footnote button to create a numbered reference that readers can easily navigate to and from.

Due to the differences between printed and digital content, the footnotes in CKEditor 5 are actually grouped together, like endnotes, and not at the bottom of each page.

<a id="ckeditor5/latest/features/footnotes.html--demo">

### Demo

Point your cursor to where you need to add a footnote and use the toolbar footnote button to add one. You can also edit existing footnotes and choose marker style by clicking in the footnotes area.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/footnotes.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

Please note that the `FootnotesProperties` plugin is optional. See the [Configuration](#ckeditor5/latest/features/footnotes.html--configuration) section for more details.

<a id="ckeditor5/latest/features/footnotes.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/footnotes.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/footnotes.html--multi-block-footnotes">

#### Multi-block footnotes

The footnotes feature can be configured using the `footnotes.multiBlock` option. By default, this option is set to `true`, allowing users to create footnotes that span multiple blocks of content. You can disable this feature by setting `multiBlock` to `false` in the editor configuration:

```
ClassicEditor
    .create( {
        footnotes: {
            multiBlock: false // Default: true
        }
    } )

```

When `multiBlock` is set to `true`, users can add footnotes that span multiple blocks of content, such as paragraphs or list items. This allows for more complex annotations and references within the document.

When `multiBlock` is set to `false`, users can only add footnotes to single blocks of content. This is useful for simpler documents where footnotes are only needed for specific points within a block. The content of the footnote definition will be limited to text only.

<a id="ckeditor5/latest/features/footnotes.html--the-footnotesproperties-contextual-balloon">

#### The `FootnotesProperties` contextual balloon

The optional `FootnotesProperties` plugin (as seen imported in the [Installation](#ckeditor5/latest/features/footnotes.html--installation) section) adds a contextual dropdown that appears when you click the footnotes definitions area. It provides quick access to footnote formatting options, allowing users to change the marker numbering style.

The [FootnotesProperties](../api/module%5Ffootnotes%5Ffootnotesproperties-FootnotesProperties.html) plugin provides additional configuration option to choose the default style of the list item markers:

```
ClassicEditor
    .create( {
        footnotes: {
            footnotesProperties: {
                // The default footnotes list style for newly created footnotes lists.
                // It can be changed using the 'Footnotes style' dropdown in the editor UI.
                defaultListStyle: 'decimal', // Default: 'decimal'

                // The starting index for the footnotes list numbering.
                // It can be changed using the 'start' dropdown in the editor UI.
                // Note: The starting index must be a positive integer greater or equal to 0.
                defaultStartIndex: 1, // Default: 1

                // Configuration of the footnotes style dropdown shown when the user clicks footnotes definitions list.
                toolbar: [ 'footnotesStyle' ], // Default: [ 'footnotesStyle' ]

                // List of styles available in the footnotes style dropdown.
                listStyles: [ 'decimal' ] // Default: [ 'decimal', 'decimal-leading-zero', 'lower-latin', 'upper-latin', 'lower-roman', 'upper-roman' ]
            }
        }
    } )

```

Available list styles: `'decimal'`, `'decimal-leading-zero'`, `'lower-roman'`, `'upper-roman'`, `'lower-latin'`, `'upper-latin'`, `'arabic-indic'`.

The `arabic-indic` style is not shown in the dropdown by default. To enable it, add it to the `listStyles` configuration:

```
footnotes: {
    footnotesProperties: {
        listStyles: [
            'decimal',
            'decimal-leading-zero',
            'lower-latin',
            'upper-latin',
            'lower-roman',
            'upper-roman',
            'arabic-indic'
        ]
    }
}

```

<a id="ckeditor5/latest/features/footnotes.html--known-issues">

### Known issues

Moving the footnotes list while [Track Changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) is enabled is not supported - a document can contain at most one footnotes list. As a workaround, temporarily disable track changes or accept/reject the relevant changes, then perform the move.

<a id="ckeditor5/latest/features/footnotes.html--related-features">

### Related features

Check out also these CKEditor 5 features to gain better control over your content style and format:

* [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) – Allows you to enable HTML features (elements, attributes, classes, styles) that are not explicitly supported by other dedicated CKEditor 5 plugins.
* [Headings](#ckeditor5/latest/features/headings.html) – Divide your content into sections.
* [Page break](#ckeditor5/latest/features/page-break.html) – Divide your content into pages.

<a id="ckeditor5/latest/features/footnotes.html--common-api">

### Common API

The [Footnotes](../api/module%5Ffootnotes%5Ffootnotes-Footnotes.html) plugin registers:

* The ['insertFootnote' command](../api/module%5Ffootnotes%5Fcommands%5Finsertfootnotecommand-InsertFootnoteCommand.html).
* The `'insertFootnote'` UI component – a button to insert footnotes.

The [FootnotesProperties](../api/module%5Ffootnotes%5Ffootnotesproperties-FootnotesProperties.html) plugin registers:

* The ['footnotesStyle' command](../api/module%5Ffootnotes%5Ffootnotesproperties%5Fcommands%5Ffootnotesstylecommand-FootnotesStyleCommand.html).
* The `'footnotesStyle'` UI component – a dropdown to change footnotes numbering style.

<a id="ckeditor5/latest/features/footnotes.html--executing-commands">

#### Executing commands

You can insert a footnote programmatically by executing the command:

```
editor.execute( 'insertFootnote' );

```

You can also specify a custom footnote ID:

```
editor.execute( 'insertFootnote', { footnoteId: 'my-custom-footnote-id' } );

```

If the `footnoteId` parameter is not provided, a unique ID will be generated automatically. The footnote ID must be a non-empty string without spaces that does not start with a digit.

You can change the footnotes style by executing:

```
editor.execute( 'footnotesStyle', { value: 'lower-roman' } );

```

Available style values: `'decimal'`, `'decimal-leading-zero'`, `'lower-roman'`, `'upper-roman'`, `'lower-latin'`, `'upper-latin'`, `'arabic-indic'`.

<a id="ckeditor5/latest/features/format-painter.html">source file: "ckeditor5/latest/features/format-painter.html"</a>

## Format painter

The format painter feature lets you copy text formatting (such as bold, italic, font size, color, etc.) and apply it in a different place in the edited document. It helps keep the formatting consistent and speeds up the creation of rich content.

<a id="ckeditor5/latest/features/format-painter.html--demo">

### Demo

Click the text that you want to copy the formatting from and use the paint formatting toolbar button  to copy the style. Then select the target text with your mouse to apply the formatting. See below the demo for more tips on using the feature.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

* **To copy the formatting**: Place the cursor inside a text with some formatting and click the paint formatting toolbar button. Notice that the mouse cursor changes to the .
* **To paint with the copied formatting**: Click any word in the document and the new formatting will be applied. Alternatively, instead of clicking a single word, you can select a text fragment (like an entire paragraph). Notice that the cursor will go back to the default one after the formatting is applied.
* **To keep painting using the same formatting**: Open the toolbar dropdown and enable the continuous painting mode. Once copied, the same formatting can be applied multiple times in different places until the paint formatting button is clicked (the cursor will then revert to the regular one).

<a id="ckeditor5/latest/features/format-painter.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/format-painter.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/format-painter.html--integration">

### Integration

The format painter feature only supports the [text attributes](#ckeditor5/latest/framework/architecture/editing-engine.html--text-attributes) with the [isFormatting](../api/module%5Fengine%5Fmodel%5Fschema-ModelAttributeProperties.html#member-isFormatting) [property](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-setAttributeProperties) set to `true`.

If you want your custom feature to become compatible with format painter, make sure you set the `isFormatting` property in your feature’s [schema](#ckeditor5/latest/framework/deep-dive/schema.html) configuration to `true`:

```
// Allow myAttribute attribute on text nodes.
editor.model.schema.extend( '$text', { allowAttributes: 'myAttribute' } );

// Integration with the format painter feature.
editor.model.schema.setAttributeProperties( 'myAttribute', {
isFormatting: true
} );

```

If you want to enable format painter for existing features that are not supported out of the box, such as the [link feature](#ckeditor5/latest/features/link.html), set the `isFormatting` property to `true` on a related text attribute:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
    } )
    .then( editor => {
        // Enable format painter for links. The link feature uses the "linkHref" text attribute.
        editor.model.schema.setAttributeProperties( 'linkHref', {
            isFormatting: true
        } );
    } );

```

You can use the [CKEditor 5 inspector](#ckeditor5/latest/framework/develpment-tools/inspector.html) to learn about the model structure of the content brought by other features.

<a id="ckeditor5/latest/features/format-painter.html--limitations">

### Limitations

Not all formatting can be handled by the format painter out of the box.

* Painting with block-level formatting (like [headings](#ckeditor5/latest/features/headings.html) or [image styles](#ckeditor5/latest/features/images/images-styles.html)) is not supported yet.  
Neither [links](#ckeditor5/latest/features/link.html) nor [text highlights](#ckeditor5/latest/features/highlight.html) are handled by the format painter. This is because, in CKEditor 5, they are considered a part of the content rather than text formatting. However, you can [work around this](#ckeditor5/latest/features/format-painter.html--integration) if needed.

<a id="ckeditor5/latest/features/format-painter.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you format your content:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_ and others.
* [Font styles](#ckeditor5/latest/features/font.html) – Control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), and [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the text on the go using Markdown.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/format-painter.html--common-api">

### Common API

The [FormatPainter](../api/module%5Fformat-painter%5Fformatpainter-FormatPainter.html) plugin registers:

* The `'formatPainter'` UI button (dropdown) component for the toolbar.
* The `'copyFormat'` command implemented by [CopyFormatCommand](../api/module%5Fformat-painter%5Fcopyformatcommand-CopyFormatCommand.html).
* The `'pasteFormat'` command implemented by [PasteFormatCommand](../api/module%5Fformat-painter%5Fpasteformatcommand-PasteFormatCommand.html).

You can copy the formatting of the current document selection using the editor API:

```
editor.execute( 'copyFormat' );

```

The copied formatting is stored in the [value of the copyFormat command](../api/module%5Fformat-painter%5Fcopyformatcommand-CopyFormatCommand.html#member-value):

```
// Logs the copied formatting.
console.log( editor.commands.get( 'copyFormat' ).value );

```

The previously copied formatting can be applied in a different place using the following code:

```
editor.execute( 'pasteFormat' );

```

<a id="ckeditor5/latest/features/fullscreen.html">source file: "ckeditor5/latest/features/fullscreen.html"</a>

## Fullscreen mode

The fullscreen mode lets you temporarily expand the editor to the whole browser viewport, giving you more space to comfortably edit content and use editor’s UI features.

<a id="ckeditor5/latest/features/fullscreen.html--demo">

### Demo

Use the fullscreen mode toolbar button  in the editor below to see the feature in action. Once you enter the fullscreen mode, you will notice the following changes:

* Editor UI is stretched to the whole browser viewport.
* Menu bar is visible by default, regardless of its presence outside fullscreen.
* The editor editable area dimensions are changed.
* Some dialogs are re-positioned to better utilize the increased space.
* Website scroll is disabled.
* Annotations display mode is switched to wide sidebar (this affects only annotations UIs without filter function configured).

Fullscreen mode can also be toggled using the Ctrl+Shift+F (or Cmd+Shift+F) keystroke.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/fullscreen.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/fullscreen.html--supported-editor-types">

### Supported editor types

Fullscreen mode is ready-to-use for [classic](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor) and [decoupled](#ckeditor5/latest/getting-started/setup/editor-types.html--decoupled-editor-document) editors. If you want to use it with other editor type, you can use custom callbacks to adjust the layout according to your needs. See the details in the [Enabling other editor types](#ckeditor5/latest/features/fullscreen.html--enabling-other-editor-types) section.

<a id="ckeditor5/latest/features/fullscreen.html--configuration">

### Configuration

Fullscreen mode is designed to provide a great editing experience without requiring any additional effort from the integrator. It provides integration with most of the official CKEditor 5 features out-of-the-box, detecting which of them are available. At the same time, it is possible to fully customize how the fullscreen mode is displayed, either through configuration flags, custom CSS definitions or by providing a custom callback that will execute more complex changes.

<a id="ckeditor5/latest/features/fullscreen.html--menu-bar-visibility">

#### Menu bar visibility

By default, menu bar is visible in fullscreen mode for any [supported editor type](#ckeditor5/latest/features/fullscreen.html--supported-editor-types), regardless of their original configuration. To disable it, use the `config.fullscreen.menuBar.isVisible` option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fullscreen: {
            menuBar: {
                isVisible: false
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Note that this setting does not change the original behavior defined in `config.menuBar.isVisible` configuration option.

<a id="ckeditor5/latest/features/fullscreen.html--toolbar-grouping">

#### Toolbar grouping

Toolbar grouping in fullscreen mode will behave the same as outside it. To define the behavior explicitly, use `config.fullscreen.toolbar.shouldNotGroupWhenFull` option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fullscreen: {
            toolbar: {
                shouldNotGroupWhenFull: true
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Note that this setting does not change the original behavior defined in `config.toolbar.shouldNotGroupWhenFull` configuration option.

<a id="ckeditor5/latest/features/fullscreen.html--using-a-custom-container">

#### Using a custom container

If you want to use the fullscreen mode to enhance the editing experience but still need certain elements of your website layout to remain visible, you can specify a custom container for the editor using the `config.fullscreen.container` property. The editor will be resized to match the dimensions of the specified container.

**Important:** Be sure the container element has a positioning context (meaning, its `position` is not set to `static`) – typically `relative`, `absolute`, or `fixed`. This ensures the editor is correctly positioned and sized within the container.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        fullscreen: {
            container: document.querySelector( '.fullscreen-editor-container' )
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

When using a custom container, the website scroll will not be locked to allow for accessing the rest of the website content.

<a id="ckeditor5/latest/features/fullscreen.html--further-customization">

### Further customization

Besides basic configuration, it is possible to do virtually any changes to the fullscreen mode layout using CSS and custom configurable callbacks.

<a id="ckeditor5/latest/features/fullscreen.html--basic-template">

#### Basic template

To change the component styling (like editable area width or background color), you can use the CSS classes (precede each with `.ck.ck-fullscreen__main-wrapper` selector to ensure enough CSS specificity):

* `ck-fullscreen__top-wrapper` \- top wrapper holding the menu bar and toolbar.
* `ck-fullscreen__menu-bar` \- container with menu bar.
* `ck-fullscreen__toolbar` \- container with toolbar.
* `ck-fullscreen__editable-wrapper` \- container with sidebars and editable area.
* `ck-fullscreen__sidebar` \- this class is assigned to both left and right sidebar.
* `ck-fullscreen__left-sidebar` \- class that only left sidebar has.
* `ck-fullscreen__right-sidebar` \- class that only right sidebar has.
* `ck-fullscreen__editable` \- container with the editable area.
* `ck-fullscreen__bottom-wrapper` \- empty container that can be used for footer-like features.

<a id="ckeditor5/latest/features/fullscreen.html--callbacks">

#### Callbacks

If you want to display some additional elements in the fullscreen mode, set the `config.fullscreen.onEnterCallback` and `config.fullscreen.onLeaveCallback` properties.

`onEnterCallback( container )` is fired when you enter fullscreen mode. Passed parameter is the final DOM element container generated by the default fullscreen behavior. It contains the whole fullscreen mode DOM structure, already set up (the editor UI is already injected into the container). You are free to perform any changes, for example, relocate sidebars or append additional UI elements.

`onLeaveCallback( container )` is fired when you leave fullscreen mode. Passed parameter is the container with the fullscreen mode DOM structure. The callback should be used to take care of any of your custom components, for example, if some elements were moved to the fullscreen DOM structure, restore their original locations in the DOM.

<a id="ckeditor5/latest/features/fullscreen.html--demo-customized-layout-pageless-editor">

#### Demo - customized layout: pageless editor

Below you will find a customized demo:

* Instead of occupying the whole viewport, the editor is stretched only over the main website area, not covering the top and side navigation bars.
* The “piece of paper” view is replaced by the “pageless” view, replicating the [classic editor](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor) experience.
* Menu bar is not displayed.

<a id="ckeditor5/latest/features/fullscreen.html--enabling-other-editor-types">

#### Enabling other editor types

This section covers how to provide fullscreen mode integration for other [editor types](#ckeditor5/latest/getting-started/setup/editor-types.html) than classic and decoupled. Please note that only these two editor types are officially supported, so the code snippets below are exemplary and may not solve all technical challenges.

First, you need to create a custom class extending [FullscreenAbstractEditorHandler](../api/module%5Ffullscreen%5Fhandlers%5Fabstracteditorhandler-FullscreenAbstractEditorHandler.html). Besides the optional typing improvements, the most important thing is to implement its custom [#defaultOnEnter()](../api/module%5Ffullscreen%5Fhandlers%5Fabstracteditorhandler-FullscreenAbstractEditorHandler.html#function-defaultOnEnter) method. It should move the editor UI elements proper for your editor type to the fullscreen container, preferably using [#moveToFullscreen()](../api/module%5Ffullscreen%5Fhandlers%5Fabstracteditorhandler-FullscreenAbstractEditorHandler.html#function-moveToFullscreen) helper - it will assure the elements are moved back in DOM when leaving fullscreen mode.

Then, in the editor’s `toggleFullscreen` command, you will need to substitute the [#fullscreenHandler](../api/module%5Ffullscreen%5Ffullscreencommand-FullscreenCommand.html#member-fullscreenHandler) property with an instance of your custom class. It can be done by adding a custom plugin that should be later added to the editor configuration (see the full example below).

```
import { FullscreenAbstractEditorHandler, FullscreenEditing } from '@ckeditor/ckeditor5-fullscreen';
import { Plugin } from '@ckeditor/ckeditor5-core';

class CustomEditorHandler extends FullscreenAbstractEditorHandler {
    // It's not mandatory to override `#_editor` property, but that will help TypeScript to properly handle the class.
    // Skip if you are not using TS.
    protected override readonly _editor: CustomEditorClass;

    // Assign the custom editor class.
    constructor( editor: CustomEditorClass ) {
        super( editor );

        this._editor = editor;
    }

    public override defaultOnEnter() {
        // Implement your fullscreen logic here.
        // For DOM manipulation, use `this.moveToFullscreen()` helper to ensure the elements are properly cleaned up
        // after leaving fullscreen mode.
    }
}

class CustomFullscreenHandling extends Plugin {
    // Ensure 'toggleFullscreen' command, registered in `FullscreenEditing` plugin, is already available in the editor.
    public static get requires() {
        return [ FullscreenEditing ] as const;
    }

    init() {
        // Substitute the default editor handler with a custom one.
        this.editor.commands.get( 'toggleFullscreen' ).fullscreenHandler = new CustomEditorHandler( this.editor );
    }
}

CustomEditorClass
    .create( {
        // Other configuration options.
        plugins: [ Fullscreen, CustomFullscreenHandling,
            // Other plugins.
        ]
    } );

```

<a id="ckeditor5/latest/features/fullscreen.html--related-features">

### Related features

Here are some CKEditor 5 features that are a perfect match for fullscreen mode:

* [Document outline](#ckeditor5/latest/features/document-outline.html) – Display the list of all document headings next to the editing area.
* [Track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Mark user changes in the content and show them as suggestions in the sidebar for acceptance or rejection.
* [Real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) – Work on the same document with other users simultaneously.

<a id="ckeditor5/latest/features/fullscreen.html--common-api">

### Common API

The fullscreen plugin registers:

* the `fullscreen` UI button components for toolbar and menu bar,
* the `toggleFullscreen` command.

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Toggle the fullscreen mode.
editor.execute( 'toggleFullscreen' );

```

<a id="ckeditor5/latest/features/fullscreen.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-fullscreen>.

<a id="ckeditor5/latest/features/headings.html">source file: "ckeditor5/latest/features/headings.html"</a>

## Headings

The heading feature helps you structure your document by adding headings to parts of the text. They make your content easier to scan by both readers and search engines.

<a id="ckeditor5/latest/features/headings.html--demo">

### Demo

Use the toolbar dropdown to style a heading. You can also type one or more `#` characters (depending on the heading level) followed by a space, and the [autoformatting feature](#ckeditor5/latest/features/autoformat.html) will create a new heading.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/headings.html--heading-levels">

### Heading levels

By default, this feature is configured to support `<h2>`, `<h3>`, and `<h4>` elements which are named: “Heading 1,” “Heading 2,” and “Heading 3,” respectively. The rationale behind starting from `<h2>` is that `<h1>` should be reserved for the [page’s main title](#ckeditor5/latest/features/title.html) and the page content will usually start from `<h2>`.

By default, when your editor preset does not include the title plugin, an `<h1>` element pasted into the rich-text editor is converted to `<h2>` (“Heading 1”).

<a id="ckeditor5/latest/features/headings.html--heading-buttons">

### Heading buttons

The heading feature lets you also use a set of heading buttons instead of the dropdown list. The toolbar buttons are configurable, and it is possible to include a paragraph button, too. Compare the heading toolbar dropdown from the demo above with the heading buttons below to check the functionality and usability of this variation.

<a id="ckeditor5/latest/features/headings.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/headings.html--installation-with-toolbar-heading-buttons">

#### Installation with toolbar heading buttons

To configure the toolbar buttons for styling text as headings and paragraphs, you need to import the following into your plugin list and configuration:

<a id="ckeditor5/latest/features/headings.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/headings.html--configuring-heading-levels">

#### Configuring heading levels

You can configure which heading levels the editor will support and how they should be named in the Headings dropdown. Use the [heading.options](../api/module%5Fheading%5Fheadingconfig-HeadingConfig.html#member-options) configuration option to do so.

For example, the following editor will support only two levels of headings – `<h1>` and `<h2>`:

```
<div id="editor">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
</div>

```

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/headings.html--configuring-custom-heading-elements">

#### Configuring custom heading elements

It is also possible to define fully custom elements for headings by using the [advanced format](../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-elementToElement) of the [heading.options](../api/module%5Fheading%5Fheadingconfig-HeadingConfig.html#member-options) configuration option.

For example, the following editor will support the following two heading options at the same time: `<h2 class="fancy">` and `<h2>`:

```
<style>
    /* Styles for the heading in the content and for the dropdown item. */
    h2.fancy, .ck.ck-button.ck-heading_heading2_fancy {
        color: #ff0050;
        font-size: 17px;
    }
</style>

<div id="snippet-custom-heading-levels">
    <h1>Heading 1</h1>
    <h2>Heading 2</h2>
    <h2 class="fancy">Fancy Heading 2</h2>
    <p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
</div>

```

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                {
                    model: 'headingFancy',
                    view: {
                        name: 'h2',
                        classes: 'fancy'
                    },
                    title: 'Heading 2 (fancy)',
                    class: 'ck-heading_heading2_fancy',

                    // It needs to be converted before the standard 'heading2'.
                    converterPriority: 'high'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/headings.html--configuring-toolbar-buttons">

#### Configuring toolbar buttons

To use individual toolbar buttons instead of the heading dropdown, you need to properly configure the feature. You also need to import proper UI elements; see the [installation section](#ckeditor5/latest/features/headings.html--installation-with-toolbar-heading-buttons) for instructions on how to do it.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', '|', 'undo', 'redo' ],
        heading: {
            options: [
                { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                { model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
                { model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/headings.html--related-features">

### Related features

There are more CKEditor 5 features that can help you format your content:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_, and others.
* [Document title](#ckeditor5/latest/features/title.html) – Clearly divide your content into a title and body.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Set indentation for text blocks such as paragraphs or lists.
* [Lists](#ckeditor5/latest/features/lists/lists.html) – Organize your content better with ordered and unordered lists you can style.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Add formatting elements (such as headings) as you type with Markdown code.

<a id="ckeditor5/latest/features/headings.html--common-api">

### Common API

The [Heading](../api/module%5Fheading%5Fheading-Heading.html) plugin registers:

* The `'heading'` dropdown.
* The `'heading'` command that accepts a value based on the [heading.options](../api/module%5Fheading%5Fheadingconfig-HeadingConfig.html#member-options) configuration option.  
You can turn the currently selected block(s) to headings by executing one of these commands:  
```  
editor.execute( 'heading', { value: 'heading2' } );  
```

The [HeadingButtonsUI](../api/module%5Fheading%5Fheadingbuttonsui-HeadingButtonsUI.html) plugin registers six UI button components that will execute the `'heading'` command with the proper value of the `value` attribute:

* `'heading1'`
* `'heading2'`
* `'heading3'`
* `'heading4'`
* `'heading5'`
* `'heading6'`

The [ParagraphButtonUI](../api/module%5Fparagraph%5Fparagraphbuttonui-ParagraphButtonUI.html) plugin registers the UI button component: `'paragraph'`.

<a id="ckeditor5/latest/features/headings.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-heading>.

<a id="ckeditor5/latest/features/highlight.html">source file: "ckeditor5/latest/features/highlight.html"</a>

## Highlight

The highlight feature lets you mark text fragments with different colors. You can use it both as a marker (to change the background color) and as a pen (to change the text color).

<a id="ckeditor5/latest/features/highlight.html--demo">

### Demo

Select the text you want to highlight. Then use the highlight toolbar button  to choose a desired color from the dropdown.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/highlight.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/highlight.html--configuring-the-highlight-options">

### Configuring the highlight options

The highlight feature comes with flexible configuration options.

However, the plugin has a predefined and limited number of available colors. It also focuses more on functionality than aesthetics. To change the text and background colors, use the [font color and background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features) plugin.

The highlight feature uses inline `<mark>` elements in the view.

<a id="ckeditor5/latest/features/highlight.html--dropdown">

#### Dropdown

You can configure which highlight options are supported by the editor. Use the [highlight.options](../api/module%5Fhighlight%5Fhighlightconfig-HighlightConfig.html#member-options) configuration and define your highlight styles.

For example, the following editor supports two styles (a green marker and a red pen):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        highlight: {
            options: [
                {
                    model: 'greenMarker',
                    class: 'marker-green',
                    title: 'Green marker',
                    color: 'var(--ck-content-highlight-marker-green)',
                    type: 'marker'
                },
                {
                    model: 'redPen',
                    class: 'pen-red',
                    title: 'Red pen',
                    color: 'var(--ck-content-highlight-pen-red)',
                    type: 'pen'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/highlight.html--inline-buttons">

#### Inline buttons

Instead of using the (default) `'highlight'` button, the feature also supports a configuration with separate buttons available directly in the toolbar:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        toolbar: {
            items: [
                'heading',
                '|',
                'highlight:yellowMarker', 'highlight:greenMarker', 'highlight:pinkMarker',
                'highlight:greenPen', 'highlight:redPen', 'removeHighlight',
                '|',
                'undo', 'redo'
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/highlight.html--colors-and-styles">

#### Colors and styles

<a id="ckeditor5/latest/features/highlight.html--using-css-variables">

##### Using CSS variables

The highlight feature is using the power of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables) defined in the [style sheet](https://github.com/ckeditor/ckeditor5-highlight/blob/master/theme/highlight.css). Thanks to that, both the UI and the content styles share the same color definitions that you can customize:

```
:root {
    /* Make green a little darker. */
    --ck-content-highlight-marker-green: #199c19;

    /* Make the yellow more "dirty". */
    --ck-content-highlight-marker-yellow: #cac407;

    /* Make red more pinkish. */
    --ck-content-highlight-pen-red: #ec3e6e;
}

```

<a id="ckeditor5/latest/features/highlight.html--inline-color-definitions">

##### Inline color definitions

You can use inline color values in the `rgba(R, G, B, A)`, `#RRGGBB[AA]`, or `hsla(H, S, L, A)` formats instead of CSS variables. To do that, customize the [options](../api/module%5Fhighlight%5Fhighlightconfig-HighlightConfig.html#member-options) and define the `color` property for each option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        highlight: {
            options: [
                {
                    model: 'greenMarker',
                    class: 'marker-green',
                    title: 'Green marker',
                    color: 'rgb(25, 156, 25)',
                    type: 'marker'
                },
                {
                    model: 'yellowMarker',
                    class: 'marker-yellow',
                    title: 'Yellow marker',
                    color: '#cac407',
                    type: 'marker'
                },
                {
                    model: 'redPen',
                    class: 'pen-red',
                    title: 'Red pen',
                    color: 'hsl(343, 82%, 58%)',
                    type: 'pen'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Then, update the classes in the style sheet so the content corresponds to the UI of the editor. The UI buttons and the actual highlights in the text should be the same color.

```
.marker-green {
    background-color: rgb(25, 156, 25);
}
.marker-yellow {
    background-color: #cac407;
}
.pen-red {
    color: hsl(343, 82%, 58%);
}

```

<a id="ckeditor5/latest/features/highlight.html--related-features">

### Related features

CKEditor 5 has more features that can help you style your content:

* [Styles](#ckeditor5/latest/features/style.html) – Apply pre-configured styles like highlight or spoiler to existing content elements.
* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_, and others.
* [Font styles](#ckeditor5/latest/features/font.html) – Control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Format painter](#ckeditor5/latest/features/format-painter.html) – Easily copy text formatting and apply it in a different place in the edited document.
* [Block quote](#ckeditor5/latest/features/block-quote.html) – Include block quotations or pull quotes in your rich-text content.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/highlight.html--common-api">

### Common API

The [Highlight](../api/module%5Fhighlight%5Fhighlight-Highlight.html) plugin registers:

* The `'highlight'` dropdown.
* The ['highlight'](../api/module%5Fhighlight%5Fhighlightcommand-HighlightCommand.html) command.  
The number of options and their names correspond to the [highlight.options](../api/module%5Fhighlight%5Fhighlightconfig-HighlightConfig.html#member-options) configuration option.  
You can change the highlight of the current selection by executing the command with a desired value:  
```  
editor.execute( 'highlight', { value: 'yellowMarker' } );  
```  
The `value` corresponds to the `model` property in the configuration object. For the default configuration:  
```  
highlight.options = [  
    { model: 'yellowMarker', class: 'marker-yellow', title: 'Yellow Marker', color: 'var(--ck-content-highlight-marker-yellow)', type: 'marker' },  
    { model: 'greenMarker', class: 'marker-green', title: 'Green marker', color: 'var(--ck-content-highlight-marker-green)', type: 'marker' },  
    { model: 'pinkMarker', class: 'marker-pink', title: 'Pink marker', color: 'var(--ck-content-highlight-marker-pink)', type: 'marker' },  
    { model: 'blueMarker', class: 'marker-blue', title: 'Blue marker', color: 'var(--ck-content-highlight-marker-blue)', type: 'marker' },  
    { model: 'redPen', class: 'pen-red', title: 'Red pen', color: 'var(--ck-content-highlight-pen-red)', type: 'pen' },  
    { model: 'greenPen', class: 'pen-green', title: 'Green pen', color: 'var(--ck-content-highlight-pen-green)', type: 'pen' }  
]  
```  
the `'highlight'` command will accept the corresponding strings as values:

  * `'yellowMarker'` – available as the `'highlight:yellowMarker'` button,
  * `'greenMarker'` – available as the `'highlight:greenMarker'` button,
  * `'pinkMarker'` – available as the `'highlight:pinkMarker'` button,
  * `'blueMarker'` – available as the `'highlight:blueMarker'` button,
  * `'redPen'` – available as the `'highlight:redPen'` button,
  * `'greenPen'` – available as the `'highlight:greenPen'` button.  
Passing an empty `value` will remove any `highlight` attribute from the selection:  
```  
editor.execute( 'highlight' );  
```

<a id="ckeditor5/latest/features/highlight.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-highlight>.

<a id="ckeditor5/latest/features/horizontal-line.html">source file: "ckeditor5/latest/features/horizontal-line.html"</a>

## Horizontal line

The horizontal line feature lets you visually divide your content into sections by inserting horizontal lines (also known as horizontal rules). It is an easy way to organize the content or indicate a change of topic.

<a id="ckeditor5/latest/features/horizontal-line.html--demo">

### Demo

To insert a horizontal line in the demo below, use the toolbar button . Alternatively, start a new line with `---`. The [autoformatting feature](#ckeditor5/latest/features/autoformat.html) will turn it into a horizontal line.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/horizontal-line.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/horizontal-line.html--related-features">

### Related features

CKEditor 5 has more features that can help you better organize your document content:

* [Headings](#ckeditor5/latest/features/headings.html) – Organize your content into thematic sections.
* [Page break](#ckeditor5/latest/features/page-break.html) – Divide your document into pages.
* [Document title](#ckeditor5/latest/features/title.html) – Clearly separate the title from the body.
* [Lists](#ckeditor5/latest/features/lists/lists.html) – Create ordered (numbered) and unordered (bulleted) lists.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the content on the go with Markdown code.

<a id="ckeditor5/latest/features/horizontal-line.html--common-api">

### Common API

The [HorizontalLine](../api/module%5Fhorizontal-line%5Fhorizontalline-HorizontalLine.html) plugin registers:

* the UI button component (`'horizontalLine'`),
* the `'horizontalLine'` command implemented by [HorizontalLineCommand](../api/module%5Fhorizontal-line%5Fhorizontallinecommand-HorizontalLineCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Inserts a horizontal line into the selected content.
editor.execute( 'horizontalLine' );

```

<a id="ckeditor5/latest/features/horizontal-line.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-horizontal-line>.

<a id="ckeditor5/latest/features/html/full-page-html.html">source file: "ckeditor5/latest/features/html/full-page-html.html"</a>

## Full page HTML

Thanks to the full page HTML feature you can use CKEditor 5 to edit entire HTML pages (from `<html>` to `</html>`), including the page metadata. While the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) feature focuses on elements inside the content (the document’s `<body>`), this feature enables markup mostly invisible to the end user.

<a id="ckeditor5/latest/features/html/full-page-html.html--demo">

### Demo

Use the [Enhanced source code editing feature](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) toolbar button  to view and edit the HTML source of the document. Pay attention to the underlying markup.

<a id="ckeditor5/latest/features/html/full-page-html.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/html/full-page-html.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/html/full-page-html.html--render-styles">

#### Render styles

By default, the full page HTML feature does not render the CSS from `<style>` that may be located in the `<head>` section edited content. To enable that possibility, set the [config.htmlSupport.fullPage.allowRenderStylesFromHead](../../api/module%5Fhtml-support%5Fgeneralhtmlsupportconfig-GHSFullPageConfig.html#member-allowRenderStylesFromHead) option to `true`.

Plugin extracts `<style>` elements from the edited content moves them to the main document `<head>`, and renders them. When CSS in `<style>` tag is changed using, for example, the [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) feature, previously added `<style>` elements to the main document `<head>` will be replaced by the new ones.

However, by enabling the ability to render CSS from `<style>` elements located in the `<head>` section of the edited content, you expose the users of your system to the **risk of executing malicious code inside the editor**. Therefore, we highly recommend sanitizing your CSS using some library that will strip the malicious code from the styles before rendering them. You can plug in the sanitizer by defining the [config.htmlSupport.fullPage.sanitizeCss](../../api/module%5Fhtml-support%5Fgeneralhtmlsupportconfig-GHSFullPageConfig.html#member-sanitizeCss) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        htmlSupport: {
            fullPage: {
                allowRenderStylesFromHead: true,
                // Strip unsafe properties and values, for example:
                // values like url( ... ) that may execute malicious code
                // from an unknown source.
                sanitizeCss( CssString ) {
                    const sanitizedCss = sanitize( CssString );

                    return {
                        css: sanitizedCss,
                        // true or false depending on whether
                        // the sanitizer stripped anything.
                        hasChanged: true
                    };
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/html/full-page-html.html--security">

#### Security

It is a plain security risk. The user may provide a CSS mistakenly copied from a malicious website. It could also end up in the user’s clipboard (as it would usually be copied and pasted) by any other means.

You can instruct some advanced users to never paste CSS code from untrusted sources. However, in most cases, it is highly recommended to secure the system by configuring the Full page HTML feature to use a CSS sanitizer and, optionally, by setting strict Content Security Policy (CSP) rules.

<a id="ckeditor5/latest/features/html/full-page-html.html--sanitizer">

##### Sanitizer

The [config.htmlSupport.fullPage.sanitizeCss](../../api/module%5Fhtml-support%5Fgeneralhtmlsupportconfig-GHSFullPageConfig.html#member-sanitizeCss) option allows plugging an external sanitizer.

<a id="ckeditor5/latest/features/html/full-page-html.html--csp">

##### CSP

In addition to using a sanitizer, you can use the built-in browser mechanism called [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). By using CSP, you can let the browser know the allowed sources that CSS can use.

<a id="ckeditor5/latest/features/html/full-page-html.html--additional-feature-information">

### Additional feature information

Here are some examples of the HTML elements you can enable with this plugin:

* The HTML DOCTYPE preamble: `<!DOCTYPE html>`
* The HTML root element: `<html>`
* The head element: `<head>`
* The document’s title: `<title>`
* Meta tags inside the head element, like: `<meta name="description" content="Meta description">`

<a id="ckeditor5/latest/features/html/full-page-html.html--related-features">

### Related features

CKEditor 5 has other features related to HTML editing that you may want to check:

* [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) – Allows you to enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.
* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) – Allows for viewing and editing the source code of the document in a handy modal window (compatible with all editor types) with syntax highlighting, autocompletion and more.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Allows embedding an arbitrary HTML snippet in the editor.

<a id="ckeditor5/latest/features/html/general-html-support.html">source file: "ckeditor5/latest/features/html/general-html-support.html"</a>

## General HTML Support

With the General HTML Support (GHS) feature, developers can enable HTML features that are not supported by any other dedicated CKEditor 5 plugins. GHS lets you add elements, attributes, classes, and styles to the source. It also ensures this markup stays in the editor window and in the output.

<a id="ckeditor5/latest/features/html/general-html-support.html--demo">

### Demo

Use the [Enhanced source code editing feature](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) toolbar button  to view and edit the HTML source of the document. You can find the configuration of this snippet below the demo.

You can configure the General HTML Support feature using the `config.htmlSupport` property. With this property, you need to list the HTML features that should be handled by GHS.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/html/general-html-support.html--additional-feature-information">

### Additional feature information

Here are some examples of HTML features that you can enable using General HTML Support:

* The `<section>`, `<article>`, and `<div>` elements.
* The `<audio>`, `<video>`, and `<iframe>` elements.
* The `<span>` and `<cite>` elements.
* Some attributes of existing dedicated CKEditor 5 features:  
  * The `data-*` and `id` attributes on, for example, `<p>` and `<h1-h6>`.
  * The `style` and `classes` attributes on, for example, `<strong>` and `<a>`.

You can load (for example, via `editor.setData()`), paste, output (for example, via `editor.getData()`) the enabled HTML features. They are also visible in the editing area. To a limited extent, you can also edit such content in the editor. Read more about it in the [Level of support](#ckeditor5/latest/features/html/general-html-support.html--level-of-support) section.

<a id="ckeditor5/latest/features/html/general-html-support.html--level-of-support">

### Level of support

The difference between specific CKEditor 5 features such as [basic styles](#ckeditor5/latest/features/basic-styles.html) or [headings](#ckeditor5/latest/features/headings.html) and the HTML features enabled by GHS is that a plugin that supports a specific HTML feature provides a complete user experience for that feature. GHS ensures only that such content is accepted by the editor.

For instance, the dedicated [bold](#ckeditor5/latest/features/basic-styles.html--available-text-styles) feature offers a toolbar button used to make the selected text bold. Together with the [autoformatting feature](#ckeditor5/latest/features/autoformat.html), it also allows for applying bold style to content by typing a Markdown shortcode (`**foo**`) in the editor. The [headings](#ckeditor5/latest/features/headings.html) feature offers a dropdown from which the user can choose a heading level and ensures that pressing Enter at the end of a heading creates a new paragraph (and not another heading).

The General HTML Support does not offer any UI for the enabled features and takes only the basic semantics of a given feature into account. If you enable support for `<div>` elements via GHS, the user will not be able to create such elements from the editor UI. The GHS will know that a `<div>` is a container element, so it can wrap other blocks (like paragraphs) but cannot be used inline (next to, for example, a `<strong>` element). In this respect, it is similar to the Advanced Content Filtering (ACF) feature from CKEditor 4 as it lets you create a list of markup tags that the editor will not strip.

Therefore, the main use cases for GHS would be:

* Ensuring backward content compatibility with legacy systems.
* Introducing basic support for missing HTML features at a low cost.

<a id="ckeditor5/latest/features/html/general-html-support.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/html/general-html-support.html--configuration">

### Configuration

By default, enabling the [GeneralHtmlSupport](../../api/module%5Fhtml-support%5Fgeneralhtmlsupport-GeneralHtmlSupport.html) plugin does not enable support for any given element. You need to configure the elements the user wants to use via the [config.htmlSupport](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-htmlSupport) option. List of predefined elements than can be enabled this way is [available further in this guide](#ckeditor5/latest/features/html/general-html-support.html--predefined-supported-elements). It is also possible to define and enable [custom elements](#ckeditor5/latest/features/html/general-html-support.html--enabling-custom-elements).

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        htmlSupport: {
            allow: [ /* HTML features to allow. */ ],
            disallow: [ /* HTML features to disallow. */ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The notation of the `allow` and `disallow` rules looks as follows:

```
[
    {
        // The element name to enable or extend with
        // the following styles, classes, and other attributes.
        name: string|regexp,

        // Styles to allow (by name, name and value, or just all).
        styles: object<string=>true|string|regexp>|array<string>|true,

        // Classes to allow (by name or just all).
        classes: array<string|regexp>|true,

        // Other attributes to allow (by name, name and value, or just all).
        attributes: object<string=>true|string|regexp>|array<string>|true,
    }
]

```

Several implementation examples:

```
htmlSupport: {
    allow: [
        // Enables plain <div> elements.
        {
            name: 'div'
        },

        // Enables plain <div>, <section>, and <article> elements.
        {
            name: /^(div|section|article)$/
        },

        // Enables <div> elements with all inline styles (but no other attributes).
        {
            name: 'div',
            styles: true
        },

        // Enables <div> elements with "foo" and "bar" classes.
        {
            name: 'div',
            classes: [ 'foo', 'bar' ]
        },

        // Adds support for "foo" and "bar" classes to the already supported
        // <p> elements (those are enabled by the dedicated paragraph feature).
        {
            name: 'p',
            classes: [ 'foo', 'bar' ]
        },

        // Enables <div> elements with foo="true" attribute and "bar" attribute that
        // can accept any value (the Boolean "true" value works as an asterisk).
        {
            name: 'div',
            attributes: {
                foo: 'true',
                bar: true
            }
        },

        // Adds support for style="color: *" to the already supported
        // <p> and <h2-h4> elements.
        {
            name: /^(p|h[2-4])$/',
            styles: { 'color': true }
        },
}

```

The General HTML Support feature distinguishes several content types, each treated a bit differently:

* Container elements (like `<section>`, `<div>`).
* Inline elements (like `<span>`, `<a>`).
* Object elements (like `<iframe>`, `<video>`).

The enabled elements will not just be available “anywhere” in the content. They still need to adhere to certain rules derived from the HTML schema and common sense. Also, the behavior of specific types of elements in the editing area will be different. For instance, the object elements will only be selectable as a whole. The inline elements will work the same as other formatting features supported by CKEditor 5 (like bold and italic) do.

<a id="ckeditor5/latest/features/html/general-html-support.html--enabling-all-html-features">

#### Enabling all HTML features

Sometimes you might want to enable all HTML features, so the editor will allow all elements and attributes. You can achieve this with a special configuration:

```
htmlSupport: {
    allow: [
        {
            name: /.*/,
            attributes: true,
            classes: true,
            styles: true
        }
    ]
}

```

This configuration will work similarly to the [allowedContent: true](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-allowedContent) option from CKEditor 4.

<a id="ckeditor5/latest/features/html/general-html-support.html--enabling-script-tags-for-legacy-use-cases">

#### Enabling script tags for legacy use cases

Scripts are blocked by default because allowing `<script>` tags in editor content would let arbitrary JavaScript run whenever that content is rendered. It creates a serious cross-site scripting (XSS) risk—content from untrusted sources (e.g., copied from a malicious site or supplied by an attacker) could steal session data, modify the page, or perform actions on behalf of the user. If you attempt to place the `<script>` tag in the content, you may see an error like this:

```
view renderer filler not found

```

Blocking scripts by default keeps the editing surface and the published output safe unless you explicitly enable scripts for a controlled, legacy scenario. For example, if you have content from CKEditor 4 and script tags are necessary. For such a case you can explicitly allow `<script>` tags using the configuration:

```
htmlSupport: {
    allow: [
        {
            name: 'script',
            attributes: true,
            classes: true,
            styles: true
        }
    ]
}

```

This configuration allows `<script>` elements along with their attributes, classes, and styles, preventing the editor from crashing when such content is loaded.

<a id="ckeditor5/latest/features/html/general-html-support.html--security">

#### Security

When you set up the GHS to allow elements like `<script>` or attributes like `onclick`, you expose the users of your application to a possibly malicious markup. This can be code mistakenly copied from a risky website or purposely provided by a bad actor. An example of that could be: `<div onclick="leakUserData()">`.

The content inside the editor (what you see in the editing area) is filtered by default from typical content that could break the editor. However, the editor does not feature a full XSS filter. We recommend configuring GHS to enable specific HTML markup instead of enabling all markup at once.

Moreover, as a general rule, not exclusive to GHS, there should always be a sanitization process present on the backend side of your application. Even the best filtering done on the browser side of your application can be mitigated, and every network call can be manipulated, thus bypassing the frontend filtering. This can quickly become a security risk.

In addition to the sanitization process and safe GHS configuration, it is highly recommended to set strict [Content Security Policy](#ckeditor5/latest/getting-started/setup/csp.html) rules.

<a id="ckeditor5/latest/features/html/general-html-support.html--iframe-sandbox">

##### Iframe sandbox

`<iframe>` elements can introduce security risks if not properly restricted. To address this, browsers support the [sandbox attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) on iframes, which restricts what the embedded content is allowed to do.

GHS automatically enforces a `sandbox` attribute on all `<iframe>` elements in the **editing view** via the built-in `IframeElementSupport` plugin. This behavior is controlled by the `htmlSupport.htmlIframeSandbox` configuration option.

The `htmlIframeSandbox` option accepts `true` (the default), an array of allowed [sandbox flag values](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox), or `false`. Setting it to `true` enforces the strictest mode — every `<iframe>` in the editing view gets an empty `sandbox=""` attribute, disabling scripts, forms, popups, and all other privileged features. Passing an array limits the sandbox to only the specified flags; any flag not on the list is stripped from existing iframes. Setting the option to `false` disables enforcement entirely and leaves the attribute untouched.

```
ClassicEditor
    .create( {
        htmlSupport: {
            // Default. Enforces empty sandbox on all iframes.
            htmlIframeSandbox: true,

            // Only these flags are kept.
            // htmlIframeSandbox: [ 'allow-scripts', 'allow-same-origin' ],

            // No enforcement — attribute is left as-is.
            // htmlIframeSandbox: false
        }
    } );

```

<a id="ckeditor5/latest/features/html/general-html-support.html--enabling-custom-elements">

#### Enabling custom elements

You can define custom HTML elements with attributes and classes.

To use a new element, you need to register it with [DataSchema](../../api/module%5Fhtml-support%5Fdataschema-DataSchema.html) as one of the types below:

* Inline element.
* Block element.

To enable such elements and add attributes or classes to them, you need to use the [allowElement](../../api/module%5Fhtml-support%5Fdatafilter-DataFilter.html#function-allowElement) and [allowAttributes](../../api/module%5Fhtml-support%5Fdatafilter-DataFilter.html#function-allowAttributes) methods from the [DataFilter](../../api/module%5Fhtml-support%5Fdatafilter-DataFilter.html) API.

Base implementation example:

You can treat both inline and block elements as object elements. To make it possible, it is necessary to set the [isObject](../../api/module%5Fhtml-support%5Fdataschema-HtmlSupportDataSchemaDefinition.html#member-isObject) property to `true`.

```
// Inline object element.
dataSchema.registerInlineElement( {
    view: 'object-inline',
    model: 'myObjectInline',
    isObject: true,
    modelSchema: {
        inheritAllFrom: '$inlineObject'
    }
} );

dataFilter.allowElement( 'object-inline' );

// Block object element.
dataSchema.registerBlockElement( {
    view: 'object-block',
    model: 'myObjectBlock',
    isObject: true,
    modelSchema: {
        inheritAllFrom: '$blockObject'
    }
} );

dataFilter.allowElement( 'object-block' );

```

<a id="ckeditor5/latest/features/html/general-html-support.html--predefined-supported-elements">

#### Predefined supported elements

The HTML elements listed below can be turned on directly via the `allow` setting of the `config.htmlSupport` option [mentioned above](#ckeditor5/latest/features/html/general-html-support.html--configuration).

<a id="ckeditor5/latest/features/html/general-html-support.html--block-elements">

##### Block elements

* address
* article
* aside
* blockquote
* button
* caption
* center
* col
* colgroup
* dd
* details
* dir
* div
* dl
* dt
* fieldset
* figcaption
* figure
* footer
* form
* header
* hgroup
* hr
* hx
* img
* input
* legend
* li
* main
* menu
* nav
* ol
* p
* pre
* section
* summary
* table
* tbody
* td
* tfoot
* th
* thead
* tr
* ul

<a id="ckeditor5/latest/features/html/general-html-support.html--inline-elements">

##### Inline elements

* a
* abbr
* acronym
* audio
* b
* bdi
* bdo
* big
* canvas
* cite
* code
* del
* dfn
* embed
* em
* figure
* font
* i
* iframe
* ins
* kbd
* li
* mark
* meter
* object
* oembed
* ol
* output
* progress
* q
* s
* samp
* script
* select
* small
* span
* strong
* style
* sub
* sup
* tbody
* thead
* time
* tt
* u
* ul
* var
* video

<a id="ckeditor5/latest/features/html/general-html-support.html--known-issues">

### Known issues

You can add support for arbitrary styles, classes, and other attributes to existing CKEditor 5 features (such as paragraphs, headings, list items, etc.). Most of the existing CKEditor 5 features can already be extended this way; however, some cannot yet.

We are open to feedback, so if you find any issue, feel free to report it in the [main CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues/).

<a id="ckeditor5/latest/features/html/general-html-support.html--related-features">

### Related features

CKEditor 5 has other features related to HTML editing that you may want to check:

* [Full page HTML](#ckeditor5/latest/features/html/full-page-html.html) – Allows using CKEditor 5 to edit entire HTML pages, from `<html>` to `</html>`, including the page metadata.
* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) – Allows for viewing and editing the source code of the document in a handy modal window (compatible with all editor types) with syntax highlighting, autocompletion and more.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Allows embedding an arbitrary HTML snippet in the editor.

<a id="ckeditor5/latest/features/html/html-comments.html">source file: "ckeditor5/latest/features/html/html-comments.html"</a>

## HTML comment element

By default, the editor filters out all HTML comments on initialization. The [HtmlComment](../../api/module%5Fhtml-support%5Fhtmlcomment-HtmlComment.html) feature lets developers keep HTML comments in the document without displaying them to the user.

<a id="ckeditor5/latest/features/html/html-comments.html--demo">

### Demo

The editor below is configured to keep HTML comments in the document content. You can view the source of the document using the [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) feature. Toggle the Enhanced source code editing mode  to see there is an HTML comment in the document source. Try uncommenting the paragraph below the picture. Once you leave the source editing mode, you will see this paragraph in the editable area.

<a id="ckeditor5/latest/features/html/html-comments.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

HTML comment feature does not require any configuration.

<a id="ckeditor5/latest/features/html/html-comments.html--known-issues">

### Known issues

The main issue with the HTML comments feature is that comments can be easily repositioned or lost in various cases (see [#10118](https://github.com/ckeditor/ckeditor5/issues/10118)).

We are open for feedback, so if you find any issue, feel free to report it in the [main CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues/).

<a id="ckeditor5/latest/features/html/html-comments.html--related-features">

### Related features

CKEditor 5 has other features related to HTML editing you may want to check:

* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) – Allows for viewing and editing the source code of the document in a handy modal window (compatible with all editor types) with syntax highlighting, autocompletion and more.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Allows embedding an arbitrary HTML snippet in the editor. It is a more constrained and controllable approach to arbitrary HTML than GHS.

<a id="ckeditor5/latest/features/html/html-comments.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-html-support>.

<a id="ckeditor5/latest/features/html/html-embed.html">source file: "ckeditor5/latest/features/html/html-embed.html"</a>

## HTML embed

The HTML embed feature lets you embed any HTML snippet in your content. The feature is meant for more advanced users who want to directly interact with HTML fragments.

<a id="ckeditor5/latest/features/html/html-embed.html--demo">

### Demo

Use the HTML embed toolbar button  in the editor below to see the plugin in action. Click the “Preview editor data” button under the editor to preview the editor content, including the embedded HTML.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/html/html-embed.html--demo-content-preview">

#### Demo content preview

<a id="ckeditor5/latest/features/html/html-embed.html--preview-data-container"> 

<a id="ckeditor5/latest/features/html/html-embed.html--additional-feature-information">

### Additional feature information

This feature lets you embed any HTML code and bypass CKEditor 5’s filtering mechanisms. You can use it to enrich content produced by CKEditor 5 with fragments of HTML that are not supported by any other CKEditor 5 feature.

Some examples of content that you can embed thanks to the HTML embed feature:

* Analytics code (that usually requires embedding `<script>` elements).
* Social page widgets (that also require embedding `<script>` elements).
* Content embeddable by `<iframe>` elements.
* HTML media elements such as `<audio>` and `<video>`.
* HTML snippets produced by external tools (for example, reports or charts).
* Interactive content that requires a combination of rich HTML and scripts.

We recommended using the [media embed](#ckeditor5/latest/features/media-embed.html) feature for embeddable media that this feature supports. You can use the HTML embed feature to handle the remaining content.

<a id="ckeditor5/latest/features/html/html-embed.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/html/html-embed.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/html/html-embed.html--content-previews">

#### Content previews

The feature is by default configured to not show previews of the HTML snippets. You can enable the previews by setting the [config.htmlEmbed.showPreviews](../../api/module%5Fhtml-embed%5Fhtmlembedconfig-HtmlEmbedConfig.html#member-showPreviews) option to `true`.

However, by showing previews of the embedded HTML snippets, you expose the users of your system to the **risk of executing malicious JavaScript code inside the editor**. Therefore, it is highly recommended to plug in some HTML sanitizer that will strip the malicious code from the created snippets before rendering their previews. You can plug in the sanitizer by defining the [config.htmlEmbed.sanitizeHtml](../../api/module%5Fhtml-embed%5Fhtmlembedconfig-HtmlEmbedConfig.html#member-sanitizeHtml) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        htmlEmbed: {
            showPreviews: true,
            sanitizeHtml: ( inputHtml ) => {
                // Strip unsafe elements and attributes, for example:
                // the `<script>` elements and `on*` attributes.
                const outputHtml = sanitize( inputHtml );

                return {
                    html: outputHtml,
                    // true or false depending on whether the sanitizer stripped anything.
                    hasChanged: true
                };
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Currently, the [feature does not execute <script> tags](https://github.com/ckeditor/ckeditor5/issues/8326) so the content that requires executing JavaScript to generate a preview will not show in the editor. However, other JavaScript code, for example, used in `on*` observers and `src="javascript:..."` attributes will be executed. You still need to enable the sanitizer.

Displaying raw HTML previews can execute malicious JS (for example via `onclick` or `javascript:`) in your site’s context. Read more about the security aspect in the next section.

<a id="ckeditor5/latest/features/html/html-embed.html--security">

#### Security

If you configure the HTML embed feature to [show content previews](#ckeditor5/latest/features/html/html-embed.html--content-previews), the HTML that the user inserts into the HTML embed widget is then rendered back to the user. \*\*If the HTML was rendered as-is, **the browser would execute any JavaScript code included in these HTML snippets in the context of your website**.

This, in turn, is a plain security risk. The HTML provided by the user might be mistakenly copied from a malicious website. It could also end up in the user’s clipboard (as it would usually be copied and pasted) by any other means.

You can instruct some advanced users to never paste HTML code from untrusted sources. However, in most cases, it is highly recommended to secure the system by configuring the HTML embed feature to use an HTML sanitizer and, optionally, by setting strict Content Security Policy (CSP) rules.

<a id="ckeditor5/latest/features/html/html-embed.html--sanitizer">

##### Sanitizer

The [config.htmlEmbed.sanitizeHtml](../../api/module%5Fhtml-embed%5Fhtmlembedconfig-HtmlEmbedConfig.html#member-sanitizeHtml) option allows plugging an external sanitizer.

Some popular JavaScript libraries that you can use include [sanitize-html](https://www.npmjs.com/package/sanitize-html) and [DOMPurify](https://www.npmjs.com/package/dompurify).

The default settings of these libraries usually strip all potentially malicious content including `<iframe>`, `<video>`, or similar elements and JavaScript code coming from trusted sources. You may need to adjust their settings to match your needs.

When `showPreviews = true`, use libraries like `DOMPurify` or `sanitize-html` to prevent XSS Attacks. Sample code may look similar to this:

```
sanitizeHtml: inputHtml => {
  const safe = DOMPurify.sanitize(inputHtml, {...});
  return { html: safe, hasChanged: safe !== inputHtml };
}

```

Adjust allowed tags/attributes (for example: permit `iframe` only from trusted domains) to balance functionality and safety. Consider pairing this with CSP for stronger security. Check the [Content previews](#ckeditor5/latest/features/html/html-embed.html--content-previews) and [Security](#ckeditor5/latest/features/html/html-embed.html--security) sections of this guide for more details.

<a id="ckeditor5/latest/features/html/html-embed.html--csp">

##### CSP

In addition to sanitizing content, you can utilize the built-in browser mechanism called [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). By using CSP, the browser recognizes allowed sources and methods of executing JavaScript code. It also allows including other resources such as style sheets, images, and fonts. Check out the dedicated [Content Security Policy](#ckeditor5/latest/getting-started/setup/csp.html) setup guide.

<a id="ckeditor5/latest/features/html/html-embed.html--related-features">

### Related features

CKEditor 5 supports a wider range of embed and code features, including:

* [Media embed](#ckeditor5/latest/features/media-embed.html) – Insert embeddable media such as YouTube or Vimeo videos and tweets into your rich text content.
* [Code blocks](#ckeditor5/latest/features/code-blocks.html) – Insert longer, multiline listings of pre-formatted code with a programming language assigned.
* [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) – Enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.

<a id="ckeditor5/latest/features/html/html-embed.html--common-api">

### Common API

The [HtmlEmbed](../../api/module%5Fhtml-embed%5Fhtmlembed-HtmlEmbed.html) plugin registers:

* The UI button component (`'htmlEmbed'`).
* The `'htmlEmbed'` command implemented by [HtmlEmbedCommand](../../api/module%5Fhtml-embed%5Fhtmlembedcommand-HtmlEmbedCommand.html).

You can execute the command using the [editor.execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Inserts an empty HTML embed.
editor.execute( 'htmlEmbed' );

// Inserts an HTML embed with some initial content.
editor.execute( 'htmlEmbed', '<b>Initial content</b>.' );

// Updates the content of a selected HTML embed.
editor.execute( 'htmlEmbed', '<b>New content.</b>' );

```

<a id="ckeditor5/latest/features/html/html-embed.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-html-embed>.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html">source file: "ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html"</a>

## Base64 image upload adapter

The Base64 image upload adapter converts inserted images into [Base64-encoded strings](https://en.wikipedia.org/wiki/Base64) in the [editor output](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html). The images are stored with other content in the database without any server-side processing.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--demo">

### Demo

Use the editor below to see the adapter in action. Open the web browser console and click the button below the editor to see the base64–encoded image in the editor output data.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--base64-upload-console">

```

```

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

Once enabled in the plugin list, the Base64 image upload adapter works out–of–the–box without any additional configuration.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--configuring-allowed-file-types">

#### Configuring allowed file types

The allowed file types that can be uploaded should actually be configured in two places:

* On the client side, in CKEditor 5, restricting image upload through the CKEditor 5 UI and commands.
* On the server side, in your server configuration.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--client-side-configuration">

##### Client-side configuration

Use the [image.upload.types](../../../api/module%5Fimage%5Fimageconfig-ImageUploadConfig.html#member-types) configuration option to define the allowed image MIME types that can be uploaded to CKEditor 5.

By default, users can upload `jpeg`, `png`, `gif`, `bmp`, `webp`, and `tiff` files. You can customize this behavior to accept, for example, SVG files (in this case use the `svg+xml` type).

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--server-side-configuration">

##### Server-side configuration

It is up to you to implement any filtering mechanisms on your server to restrict the types of images allowed to be uploaded.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--whats-next">

### What’s next

Check out the comprehensive [Image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) to learn more about different ways of uploading images in CKEditor 5.

See the [Image feature guide](#ckeditor5/latest/features/images/images-overview.html) to find out more about handling images in CKEditor 5 WYSIWYG editor.

<a id="ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-upload>.

<a id="ckeditor5/latest/features/images/image-upload/custom-upload-adapter.html">source file: "ckeditor5/latest/features/images/image-upload/custom-upload-adapter.html"</a>

## Custom upload adapter

There are several reasons why developers choose to implement custom upload adapters in CKEditor 5\. These may include server integration requirements (dependent on the existing architecture where the editor is deployed), local security and authentication rules, or business logic.

The CKEditor 5 Framework offers an open API with a set of classes for upload adapters that handle the entire upload process from when a user adds a file (for example, by dragging an image) to when the server responds, acting as a bridge between the editor and your server.

Check out this dedicated [Custom Upload Adapter](#ckeditor5/latest/framework/deep-dive/upload-adapter.html) guide, which explains how to create custom file upload functionality for the editor.

<a id="ckeditor5/latest/features/images/image-upload/custom-upload-adapter.html--whats-next">

### What’s next

Check out the comprehensive [Image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) to learn more about different ways of uploading images in CKEditor 5.

See the [Image feature guide](#ckeditor5/latest/features/images/images-overview.html) to find out more about handling images in CKEditor 5 WYSIWYG editor.

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html">source file: "ckeditor5/latest/features/images/image-upload/image-upload.html"</a>

## Image upload overview

Inserting [images](#ckeditor5/latest/features/images/images-overview.html) into content created with CKEditor 5 is quite a common task. In a properly configured rich-text editor, there are several ways for the end user to insert images:

* **Pasting** an image from the clipboard.
* **Dragging** a file from the file system.
* Selecting an image through the **file system dialog**.
* Selecting an image from the **media management tool** in your application.
* **Pasting** a URL to an image, either into the editor dialog or directly into the content.

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--demo">

### Demo

This demo is configured to use [CKBox](#ckeditor5/latest/features/file-management/ckbox.html) for image upload and management. Use the image upload button  to upload images or the CKBox button  to browse and select existing images from the file manager. It also includes the `AutoImage` plugin, which lets you [paste image URLs directly](#ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-pasting-a-url-into-the-editor).

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--how-it-works">

### How it works

Except for pasting URLs to images, all other solutions mentioned above require the image to be uploaded to a server. The server will then be responsible for providing the image URL used by CKEditor 5 to display the image in the document. The software that makes the image upload possible is called an **upload adapter**. It is a callback that tells the WYSIWYG editor how to send the file to the server. There are two main strategies for getting the image upload to work that you can adopt in your project:

* [**Official upload adapters**](#ckeditor5/latest/features/images/image-upload/image-upload.html--official-upload-adapters) – There are several features providing upload adapters developed and maintained by the CKEditor team. Some of these are simple and only enable uploading, while some, like the [CKBox asset manager](#ckeditor5/latest/features/file-management/ckbox.html), let you upload, browse, manage, and edit images. Pick the best one for your integration and let it handle the image upload in your project.
* [**Custom upload adapters**](#ckeditor5/latest/features/images/image-upload/image-upload.html--implementing-your-own-upload-adapter) – You can also create your upload adapter from scratch using the open API architecture of CKEditor 5.

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--official-upload-adapters">

### Official upload adapters

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--ckbox">

#### CKBox

CKBox is the ultimate solution for not just image upload but also file management in CKEditor 5.

It is a modern file uploader with a clean interface, automatic support for responsive images, and top-notch UX. It also provides editing capabilities like cropping, rotating, or flipping.

Thanks to the native CKEditor 5 integration, CKBox supports drag and drop file upload as well as pasting images from the clipboard, Microsoft Word, or Google Docs.

With CKBox, users can upload files and categorize them into different groups. They can also change the way the files are displayed, for example, by setting the image thumbnail size or deciding how many files are shown on one page. Files can be uploaded, deleted, renamed, and tagged. File properties like dimensions, upload date, or size are also easily accessible and can be used to sort the file view alongside a regular search.

The CKBox On-premises version offers various storage options, from local filesystem, through MySQL and Postgres databases, to AWS S3 and Azure Blob Storage solutions. The SaaS version is using a blazing-fast CDN powered by AWS S3.

[**Learn how to use CKBox in your project**](#ckeditor5/latest/features/file-management/ckbox.html).

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--uploadcare">

#### Uploadcare

Uploadcare is the ultimate solution for image upload and editing in CKEditor 5.

It is a modern file uploader with a clean interface, automatic support for responsive images, on-the-fly image optimization, fast delivery through global CDN network, multiple third party integrations and vast image editing capabilities such as cropping, filtering and adjusting image parameters.

Thanks to the native CKEditor 5 integration, Uploadcare supports drag-and-drop file upload as well as pasting images from the clipboard, Microsoft Word, or Google Docs.

With Uploadcare, users can upload files from external services like Dropbox, Facebook, Google Drive, Google Photos, OneDrive or from local computer. Images can be easily adjusted with built-in image editor. The storage is configuration-less for ease of use. It also offers reliable and fast [AWS S3 storage solution](https://uploadcare.com/docs/aws-s3-storage/).

[**Learn how to use Uploadcare in your project**](#ckeditor5/latest/features/file-management/uploadcare.html).

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--ckfinder">

#### CKFinder

The [CKFinder feature](#ckeditor5/latest/features/file-management/ckfinder.html) provides a bridge between the rich-text editor and [CKFinder](https://ckeditor.com/ckfinder/), a browser-based file uploader with server-side connectors (PHP, Java, and ASP.NET).

There are two ways you can integrate CKEditor 5 with CKFinder:

* **With the server-side connector only** – In this scenario, images dropped or pasted into the editor are uploaded to the CKFinder server-side connector running on your server.
* **With both the server-side connector and the client-side file manager** (recommended) – Images dropped and pasted into the editor are uploaded to the server (like in the first option). With access to the file manager, you can browse previously uploaded images, organize them, or edit them.

[**Learn how to integrate CKEditor 5 with CKFinder in your project**](#ckeditor5/latest/features/file-management/ckfinder.html).

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--simple-adapter">

#### Simple adapter

The [simple upload adapter](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html) allows uploading images to your server using the [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) API with a minimal editor configuration.

[**Learn how to use the simple upload adapter in CKEditor 5**](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html).

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--base64-adapter">

#### Base64 adapter

The [Base64 upload feature](#ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html) converts images inserted into the editor into [Base64 strings](https://en.wikipedia.org/wiki/Base64) in the [editor output](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html).

[**Learn how to use Base64–encoded images in CKEditor 5**](#ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html).

<a id="ckeditor5/latest/features/images/image-upload/image-upload.html--implementing-your-own-upload-adapter">

### Implementing your own upload adapter

CKEditor 5 provides an open API that allows you to develop your upload adapters. Tailored to your project, a custom adapter will allow you to take full control over the upload process. This includes both sending the files to the server and passing the response from the server (for example, the URL to the saved file) back to the WYSIWYG editor.

[**Learn how to develop a custom upload adapter for CKEditor 5**](#ckeditor5/latest/framework/deep-dive/upload-adapter.html).

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html">source file: "ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html"</a>

## Simple upload adapter

The simple upload adapter lets you upload images to your server using the [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) API with a minimal [editor configuration](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--configuration). See the [Server-side configuration](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--server-side-configuration) section to learn about the requirements for your server-side application.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--configuration">

### Configuration

The client side of this feature is configurable using the [config.simpleUpload](../../../api/module%5Fupload%5Fuploadconfig-SimpleUploadConfig.html) object.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        simpleUpload: {
            // The URL that the images are uploaded to.
            uploadUrl: 'http://example.com',

            // Enable the XMLHttpRequest.withCredentials property.
            withCredentials: true,

            // Headers sent along with the XMLHttpRequest to the upload server.
            headers: {
                'X-CSRF-TOKEN': 'CSRF-Token',
                Authorization: 'Bearer <JSON Web Token>'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--configuring-allowed-file-types">

#### Configuring allowed file types

The allowed file types that can be uploaded should be configured in two places:

* On the client side, in CKEditor 5, restricting image upload through the CKEditor 5 UI and commands.
* On the server side, in your server-side application configuration.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--client-side-configuration">

##### Client-side configuration

Use the [image.upload.types](../../../api/module%5Fimage%5Fimageconfig-ImageUploadConfig.html#member-types) configuration option to define the allowed image MIME types that can be uploaded to CKEditor 5.

By default, users are allowed to upload `jpeg`, `png`, `gif`, `bmp`, `webp`, and `tiff` files, but you can customize this behavior to accept, for example, SVG files.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--server-side-configuration">

##### Server-side configuration

It is up to you to implement any filtering mechanisms on your server to restrict the types of images that are allowed to be uploaded.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--server-side-configuration-2">

### Server-side configuration

To use this upload adapter, you must provide a server-side application that will handle the uploads and communicate with the editor, as described in the following sections.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--communication-protocol">

#### Communication protocol

When the image upload process is initiated, the adapter sends a [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request under [config.simpleUpload.uploadUrl](../../../api/module%5Fupload%5Fuploadconfig-SimpleUploadConfig.html#member-uploadUrl).

You can send additional [headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) along with the `XMLHttpRequest` to the upload server, for example, to authenticate the user, using the [config.simpleUpload.headers](../../../api/module%5Fupload%5Fuploadconfig-SimpleUploadConfig.html#member-uploadUrl) object.

If you use the [config.simpleUpload.withCredentials](../../../api/module%5Fupload%5Fuploadconfig-SimpleUploadConfig.html#member-withCredentials) configuration, you may need some [extra HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for the cross-site request to work.

The [responseType](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType) of the request is always `json`. See the [Successful upload](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--successful-upload) and [Error handling](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--error-handling) sections to learn more.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--successful-upload">

#### Successful upload

If the upload is successful, the server should return:

* An object containing the `url` property which points to the uploaded image on the server:  
```  
{  
    "url": "https://example.com/images/foo.jpg"  
}  
```
* Or an object with the `urls` property, if you want to use [responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia%5Fand%5Fembedding/Responsive%5Fimages) and the server supports it:  
```  
{  
    "urls": {  
        "default": "https://example.com/images/foo.jpg",  
        "800": "https://example.com/images/foo-800.jpg",  
        "1024": "https://example.com/images/foo-1024.jpg",  
        "1920": "https://example.com/images/foo-1920.jpg"  
    }  
}  
```  
The `"default"` URL will be used in the `src` attribute of the image in the rich-text editor content. Other URLs will be used in the `srcset` attribute, allowing the web browser to select the best one for the geometry of the viewport.

The URL(s) in the server response are used:

* To display the image during the editing (as seen by the user in the editor).
* In the editor content [saved to the database](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html).

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--error-handling">

#### Error handling

If something went wrong, the server must return an object that contains the `error` property. This will cancel the upload in the editor, for example, allowing the user to select another image if the previous one was too big or did not meet some other validation criteria.

If the `error` object contains a `message`, it will be passed to the [editor notification system](../../../api/module%5Fui%5Fnotification%5Fnotification-Notification.html#function-showWarning) and displayed to the user. For the convenience of the users, use clear and possibly specific error messages.

```
{
    "error": {
        "message": "The image upload failed because the image was too big (max 1.5MB)."
    }
}

```

If the `message` property is missing in the `error` object, the [editor notification system](../../../api/module%5Fui%5Fnotification%5Fnotification-Notification.html#function-showWarning) will display the default “Could not upload file: `[filename]`.” message.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--upload-progress">

#### Upload progress

This upload adapter will notify users about the [file upload progress](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/progress%5Fevent) out–of–the–box.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--whats-next">

### What’s next

Check out the comprehensive [Image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) to learn more about different ways of uploading images in CKEditor 5.

See the [Image feature guide](#ckeditor5/latest/features/images/images-overview.html) to find out more about handling images in CKEditor 5 WYSIWYG editor.

<a id="ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-upload>.

<a id="ckeditor5/latest/features/images/image-upload/using-file-managers.html">source file: "ckeditor5/latest/features/images/image-upload/using-file-managers.html"</a>

## Using file managers

The most convenient way to upload, manage, and insert images into content in CKEditor is by using file managers. [CKBox](https://ckeditor.com/ckbox/) and [CKFinder](https://ckeditor.com/ckfinder/) are our official file managers and file uploaders that let you upload, manage, and insert images and other files.

<a id="ckeditor5/latest/features/images/image-upload/using-file-managers.html--ckbox-file-manager">

### CKBox file manager

CKBox is a modern file management platform with a clean UI and a top-notch UX.

With CKBox you can:

* Organize images and other files into customizable categories.
* Create, rename, and delete folders.
* Delete, rename, and tag files.
* Search files and filter results by numerous properties.
* Easily access recently used files.
* View images in high-resolution full-page preview.
* Define and reuse alternative text for images.
* Get your images served quickly through global AWS S3 CDN or via local options, such as filesystem or SQL databases.

**Read the [dedicated CKBox feature guide](#ckeditor5/latest/features/file-management/ckbox.html)** to learn about its installation and configuration. The guide also lets you try CKBox in action.

<a id="ckeditor5/latest/features/images/image-upload/using-file-managers.html--uploadcare-file-manager">

### Uploadcare file manager

Uploadcare is a modern file management platform with multiple integrations with services like Dropbox, Facebook, Google Drive, Google Photos and OneDrive.

With Uploadcare you can:

* Upload images directly from:  
  * Dropbox,
  * Facebook,
  * Google Drive,
  * Google Photos,
  * OneDrive,
  * Local computer,
  * External URL.
* Manage all uploaded images through a dedicated platform.
* Edit images by changing dimensions, applying filters and adjusting various image parameters.
* Get your images served quickly through global AWS S3 CDN.

**Read the [dedicated Uploadcare feature guide](#ckeditor5/latest/features/file-management/uploadcare.html)** to learn about its installation and configuration. The guide also lets you try Uploadcare in action.

<a id="ckeditor5/latest/features/images/image-upload/using-file-managers.html--ckfinder-file-manager">

### CKFinder file manager

CKFinder is a powerful file manager with various image editing and image upload options.

With CKFinder you can:

* Group images and other files into folders and subfolders.
* Move or copy files between folders.
* Easily filter files.
* Drag and drop images and paste them from the clipboard into the editor.
* Crop, rotate, edit, and resize images.

**Read the [dedicated CKFinder feature guide](#ckeditor5/latest/features/file-management/ckfinder.html)** to learn about its installation and configuration. The guide also lets you try CKFinder in action.

<a id="ckeditor5/latest/features/images/images-captions.html">source file: "ckeditor5/latest/features/images/images-captions.html"</a>

## Image captions

The [ImageCaption](../../api/module%5Fimage%5Fimagecaption-ImageCaption.html) plugin lets you add captions to images by providing support for the `<figcaption>` element.

<a id="ckeditor5/latest/features/images/images-captions.html--demo">

### Demo

Click one of the images below and use the contextual image toolbar  to toggle the caption on and off. Click the caption to edit it.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-captions.html--additional-feature-information">

### Additional feature information

The [ImageCaption](../../api/module%5Fimage%5Fimagecaption-ImageCaption.html) plugin adds support for the `<figcaption>` element:

```
<figure class="image">
    <img src="..." alt="...">
    <figcaption>A caption goes here...</figcaption>
</figure>

```

By default, if the image caption is empty, the `<figcaption>` element is not visible to the user. You can click the image to reveal the caption field and write one.

<a id="ckeditor5/latest/features/images/images-captions.html--installation">

### Installation

To enable this feature, you need to load the [LinkImage](../../api/module%5Flink%5Flinkimage-LinkImage.html) plugin. Read more in the [installation guide](#ckeditor5/latest/features/images/images-installation.html).

<a id="ckeditor5/latest/features/images/images-captions.html--common-api">

### Common API

The [ImageCaption](../../api/module%5Fimage%5Fimagecaption-ImageCaption.html) plugin registers:

* The `'toggleImageCaption'` button (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['toggleImageCaption' command](../../api/module%5Fimage%5Fimagecaption%5Ftoggleimagecaptioncommand-ToggleImageCaptionCommand.html)

<a id="ckeditor5/latest/features/images/images-captions.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html">source file: "ckeditor5/latest/features/images/images-image-optimizer.html"</a>

## Image optimizer

Elevate your images with robust editing tools available through the premium [CKBox](#ckeditor5/latest/features/file-management/ckbox.html) and [Uploadcare](#ckeditor5/latest/features/file-management/uploadcare.html) integrations. In this guide you will discover how to modify and enhance visuals directly in the editor, giving you greater creative control.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--image-optimizer-by-uploadcare">

### Image optimizer by Uploadcare

Uploadcare provides not only basic image editing capabilities, but also image properties adjustments and photo filters, further extending CKEditor 5 feature set.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--demo">

#### Demo

Click on the image to invoke the image toolbar, then use the image editing button  to access the Uploadcare editor.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--image-editing">

#### Image editing

Image optimizer by Uploadcare provides a handful of image editing capabilities, such as:

* rotation, mirroring and flipping,
* cropping,
* [image parameters adjustment](#ckeditor5/latest/features/images/images-image-optimizer.html--image-parameter-adjustment),
* [filters](#ckeditor5/latest/features/images/images-image-optimizer.html--photo-filters).

What is great about image editing in Uploadcare is that all edits are not changing the original image. You can easily go back to the original after the cropping for examples.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--image-parameter-adjustment">

#### Image parameter adjustment

For more advanced image customization, Image optimizer by Uploadcare lets you fine-tune image parameters, ensuring you get the exact image you need. You can easily adjust brightness, exposure, gamma, contrast, saturation, vibrance and warmth.

If you are not sure which of the options would yield best results for a specific image, you can use the enhance functionality, which will adjust the image’s colors, saturation, and levels to unveil previously hidden details and bring colors to life automatically.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--photo-filters">

#### Photo filters

Image optimizer by Uploadcare also provides a wide range of predefined photo filters that can quickly change the visual style of your image. Each of the over 40 filters can be applied with variable intensity.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--configuration">

#### Configuration

To set up the editing capabilities, read the [Uploadcare documentation](#ckeditor5/latest/features/file-management/uploadcare.html--adding-image-editing-capabilities).

All features listed above are available both for images uploaded to Uploadcare before editing and – if you enable the [external images editing option](#ckeditor5/latest/features/file-management/uploadcare.html--editing-external-images) – for images from other sources (external). Keep in mind that external images will be automatically uploaded to your Uploadcare account, once you click the edit image button  to enable all the editing capabilities.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--image-optimizer-by-ckbox">

### Image optimizer by CKBox

CKBox provides image editing tools, straight from the asset manager or CKEditor 5, making working on content faster and more efficient. It saves time and resources as there is no need to resort to using a dedicated image editing software.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--demo-2">

#### Demo

Click on the image to invoke the image toolbar, then use the image editing button  to access the CKBox image editor.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--image-editing-2">

#### Image editing

CKBox premium feature provides editing capabilities such as:

* rotation, mirroring and flipping,
* cropping (freeform and to defined aspect rations),
* resizing (also to predefined presets).

All edits result in a new image being created on your CKBox account. This is done to preserve the original image, for example if it is used in other places. Editing and overwriting images is possible through the CKBox panel.

<a id="ckeditor5/latest/features/images/images-image-optimizer.html--configuration-2">

#### Configuration

To set up the editing capabilities, read the [CKBox documentation](#ckeditor5/latest/features/file-management/ckbox.html--installation).

All the listed features are available both for images uploaded to CKBox before, and – if you enable the [external images editing option](#ckeditor5/latest/features/file-management/ckbox.html--editing-external-images) – images from other sources (external). Keep in mind that external images will be instantly uploaded to your CKBox account, once you click the edit image button  to enable all the editing capabilities.

<a id="ckeditor5/latest/features/images/images-inserting.html">source file: "ckeditor5/latest/features/images/images-inserting.html"</a>

## Inserting images

You can insert images by uploading them directly from your disk, but you can also configure CKEditor 5 to let you insert images using URLs. This way you can save time by adding images that are already online.

<a id="ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-a-source-url">

### Inserting images via a source URL

<a id="ckeditor5/latest/features/images/images-inserting.html--demo">

#### Demo

To upload an image, use the image toolbar button . If you want to add an image through a URL, click the arrow next to the image button and paste the URL in the dropdown panel. To update an existing image, select it and paste a new URL in the dropdown panel.

<a id="ckeditor5/latest/features/images/images-inserting.html--installation">

#### Installation

Using the URL of an image, the user may paste it into the editor. To enable this option, install the `ImageInsert` plugin and add the `insertImage` toolbar item to the toolbar (it replaces the standard `uploadImage` button).

This will add a new **Insert image** dropdown  in the toolbar.

<a id="ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-pasting-a-url-into-the-editor">

### Inserting images via pasting a URL into the editor

<a id="ckeditor5/latest/features/images/images-inserting.html--demo-2">

#### Demo

You can paste an image URL directly into the editor content, and it will be automatically embedded.

<a id="ckeditor5/latest/features/images/images-inserting.html--installation-2">

#### Installation

The [AutoImage](../../api/module%5Fimage%5Fautoimage-AutoImage.html) plugin recognizes image links in the pasted content and embeds them shortly after they are injected into the document to speed up the editing. Accepted image extensions are: `jpg`, `jpeg`, `png`, `gif`, and `ico`. Use the following code to enable the plugin in your editor. There is no toolbar configuration for this feature.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [ /* ... */ , Image, AutoImage ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If the automatic embedding was unexpected, for instance when the link was meant to remain in the content as text, simply undo the action. Click the “Undo” button in the toolbar or use the Ctrl/Cmd+Z keystrokes.

<a id="ckeditor5/latest/features/images/images-inserting.html--common-api">

### Common API

The [Image](../../api/module%5Fimage%5Fimage-Image.html) plugin registers:

* The `'insertImage'` toolbar dropdown component that aggregates all image insert methods available in the current editor setup.
* The `'insertImageViaUrl'` toolbar button that opens a modal dialog to let you insert an image by specifying the image URL.
* The ['insertImage' command](../../api/module%5Fimage%5Fimage%5Finsertimagecommand-InsertImageCommand.html) that accepts a source (for example a URL) of an image to insert.

The [ImageUpload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin registers:

* The `'uploadImage'` toolbar button that opens the native file browser to let you upload a file directly from your disk (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['uploadImage' command](../../api/module%5Fimage%5Fimageupload%5Fuploadimagecommand-UploadImageCommand.html) that accepts the file to upload.

<a id="ckeditor5/latest/features/images/images-inserting.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-installation.html">source file: "ckeditor5/latest/features/images/images-installation.html"</a>

## Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the [subfeatures that you need](#ckeditor5/latest/features/images/images-overview.html--image-features) to your plugin list and to the editor toolbar:

<a id="ckeditor5/latest/features/images/images-installation.html--configuring-the-toolbar-dropdown">

### Configuring the toolbar dropdown

The Image feature comes with the unified image insert dropdown component . It automatically collects installed image insert methods. For example, if you install the `ImageUpload` plugin, the corresponding button will automatically appear in the dropdown. You only need to add a button to the toolbar:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        toolbar: [ 'insertImage', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The feature is pre-configured to include the following image insertion methods:

* `upload` \- Upload image from computer. It uses the configured image upload adapter.
* `assetManager` \- Opens the installed asset manager (for example the CKBox).
* `url` \- Allows inserting an image by directly specifying its URL. Integration provided by `ImageInsertViaUrl` feature.

Note that the insert methods mentioned above will only be added if you install dedicated features. However, not all features are required. If only one is available, it will be indicated by the toolbar dropdown icon.

If you need to limit the methods included in the dropdown (apart from not installing a specific feature) or change their order you can use the `image.insert.integration` configuration option:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        image: {
            insert: {
                // This is the default configuration, you do not need to provide
                // this configuration key if the list content and order reflects your needs.
                integrations: [ 'upload', 'assetManager', 'url' ]
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/images/images-installation.html--configuring-the-contextual-image-toolbar">

### Configuring the contextual image toolbar

You also need to configure the desired contextual image toolbar items. Notice the [separators](#ckeditor5/latest/getting-started/setup/toolbar.html--separating-toolbar-items) used to organize the toolbar.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        image: {
            toolbar: [
                'imageStyle:block',
                'imageStyle:side',
                '|',
                'toggleImageCaption',
                'imageTextAlternative',
                '|',
                'linkImage'
            ],
            insert: {
                // If this setting is omitted, the editor defaults to 'block'.
                // See explanation below.
                type: 'auto'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/images/images-installation.html--inline-and-block-images">

### Inline and block images

Inline images can be inserted in the middle of a paragraph or a link just like regular text. Block images, on the other hand, can be inserted only between other blocks like paragraphs, tables, or media. Being larger and existing as standalone content, block images can also have individual captions. Other than that, both types of images can be resized, linked, etc.

By default, the [Image](../../api/module%5Fimage%5Fimage-Image.html) plugin supports both inline and block images, working as a glue for the [ImageInline](../../api/module%5Fimage%5Fimageinline-ImageInline.html) and [ImageBlock](../../api/module%5Fimage%5Fimageblock-ImageBlock.html) plugins.

| Loaded plugin                | Available features |       |
| ---------------------------- | ------------------ | ----- |
| Block images (with captions) | Inline images      |       |
| Image (default)              | ✅ yes              | ✅ yes |
| ImageBlock                   | ✅ yes              | ❌ no  |
| ImageInline                  | ❌ no               | ✅ yes |

By default, if the `image.insert.type` configuration is not specified, all images inserted into the content will be treated as block images. This means that inserting an image inside a paragraph (or other content blocks) will create a new block for the image immediately below or above the current paragraph or block. After insertion, you can transform the block image into an inline image using the [contextual toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar).

If you wish to modify this behavior, the `type` setting in the editor configuration can be used:

```
ClassicEditor
    .create( {
        image: {
            insert: {
                type: 'auto'
            }
        }
    } );

```

The `type` setting accepts the following three values:

* `'auto'`: The editor determines the image type based on the cursor’s position. For example, if you insert an image in the middle of a paragraph, it will be inserted as inline. If you insert it at the end or beginning of a paragraph, it becomes a block image.
* `'block'`: Always insert images as block elements, placing them below or above the current paragraph or block.
* `'inline'`: Always insert images as inline elements within the current paragraph or block.

If the `type` setting is omitted from the configuration, the behavior defaults to inserting images as a block.

**Important**: If only one type of image plugin is enabled (for example, `ImageInline` is enabled but `ImageBlock` is not), the `image.insert.type` configuration will be effectively ignored and the supported image type will be used.

<a id="ckeditor5/latest/features/images/images-installation.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-linking.html">source file: "ckeditor5/latest/features/images/images-linking.html"</a>

## Linking images

The [LinkImage](../../api/module%5Flink%5Flinkimage-LinkImage.html) plugin lets you use images as links.

<a id="ckeditor5/latest/features/images/images-linking.html--demo">

### Demo

Click one of the images to open the contextual toolbar. Use the link icon  to add a link to the image. After you do this, an icon will appear in the top-right corner of the image, indicating there is a link attached to it.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-linking.html--additional-feature-information">

### Additional feature information

Here are some use cases where linking images can be useful:

* Linking to a high-resolution version of an image.
* Using images as thumbnails linking to an article or product page.
* Creating banners linking to other pages.

The image link can be added or edited via the image toolbar. An icon in top right corner of the image indicates the presence of a link.

An example source code for block image would look similar to this one:

```
<figure class="image">
    <a href="...">
        <img src="..." alt="...">
    </a>
    <figcaption>Image caption</figcaption>
</figure>

```

An inline image code would look more like this:

```
<a href="...">
    Some text <img src="..." alt="..." style="width: 20px">
</a>

```

<a id="ckeditor5/latest/features/images/images-linking.html--installation">

### Installation

To enable this feature, you need to load the [LinkImage](../../api/module%5Flink%5Flinkimage-LinkImage.html) plugin. Read more in the [installation guide](#ckeditor5/latest/features/images/images-installation.html).

<a id="ckeditor5/latest/features/images/images-linking.html--common-api">

### Common API

The [LinkImage](../../api/module%5Flink%5Flinkimage-LinkImage.html) plugin registers:

* The `'linkImage'` button that opens the link UI when an image is selected by the user (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['linkImage' command](../../api/module%5Flink%5Flinkcommand-LinkCommand.html).

<a id="ckeditor5/latest/features/images/images-linking.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-link>.

<a id="ckeditor5/latest/features/images/images-overview.html">source file: "ckeditor5/latest/features/images/images-overview.html"</a>

## Images in CKEditor 5 (overview)

CKEditor 5 comes with various tools to insert, upload, resize, style, caption, and link images. All these features work out of the box with block, inline, and responsive images alike.

<a id="ckeditor5/latest/features/images/images-overview.html--demo">

### Demo

To see all the image features in action, check out the demo below. To learn more about individual plugins (sub-features) of the image ecosystem, see the [**Image features**](#ckeditor5/latest/features/images/images-overview.html--image-features) section.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-overview.html--base-image-feature">

### Base image feature

The base image feature does not support any user interface for inserting or managing images. Its sole purpose is to lay ground for other plugins (listed below) to build the target user experience. This pattern (composition of atomic features) is common for CKEditor 5 and allows the developers to build their own customized experience by implementing specific subfeatures differently.

<a id="ckeditor5/latest/features/images/images-overview.html--image-features">

### Image features

The [@ckeditor/ckeditor5-image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package contains multiple plugins that implement various image-related features. The [Image](../../api/module%5Fimage%5Fimage-Image.html) plugin is at the core of the ecosystem. It provides the basic support for block and inline images. There are many other features that extend the editor’s capabilities:

* The [contextual toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar) available on mouse click gives access to image features.
* [Image captions](#ckeditor5/latest/features/images/images-captions.html) allow adding descriptive text under the image.
* The [image styles](#ckeditor5/latest/features/images/images-styles.html) help control the placement, size, and other characteristics with predefined styles.
* The [text alternative](#ckeditor5/latest/features/images/images-text-alternative.html) tag aids accessibility and SEO, provides additional image description, and supports better navigation.
* [Image resizing](#ckeditor5/latest/features/images/images-resizing.html) lets the user control the dimensions of images in the content.
* [Linking images](#ckeditor5/latest/features/images/images-linking.html) makes it possible to use them as URL anchors.
* A selection of [image upload methods](#ckeditor5/latest/features/images/image-upload/image-upload.html) allows for the most convenient way of adding images. These include support for [inserting an image via a URL](#ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-pasting-a-url-into-the-editor) and even [via pasting a URL into the editor](#ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-a-source-url) along with custom integrations.
* The [CKBox](#ckeditor5/latest/features/file-management/ckbox.html) and Uploadcare [features/uploadcare](#ckeditor5/latest/features/file-management/uploadcare.html) management platforms provide support for [responsive images](#ckeditor5/latest/features/images/images-responsive.html) in CKEditor 5\. Responsive images will display correctly on any viewport, enhancing the accessibility, reach, and user experience.
* Both Uploadcare and CKBox provide [editing and optimization capabilities](#ckeditor5/latest/features/images/images-image-optimizer.html), like cropping, resizing, rotating, and flipping right from the image contextual toolbar.

<a id="ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar">

### Image contextual toolbar

The [ImageToolbar](../../api/module%5Fimage%5Fimagetoolbar-ImageToolbar.html) plugin introduces a contextual toolbar for images. The toolbar appears when an image is selected and can be configured to contain any buttons you want. Usually, these will be image-related options such as the [text alternative](#ckeditor5/latest/features/images/images-text-alternative.html) button, the [image caption](#ckeditor5/latest/features/images/images-captions.html) button, and [image styles](#ckeditor5/latest/features/images/images-styles.html) buttons. The toolbar can also host the image editing button introduced by the [CKBox asset manager](#ckeditor5/latest/features/file-management/ckbox.html). Shown below is an example contextual toolbar with an extended set of buttons.

The image toolbar is configurable using the [config.image.toolbar](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-styles) property. For instance, to display the caption toggle, text alternative and editing buttons, use the following configuration:

```
ClassicEditor
    .create( {
        image: {
            toolbar: [ 'toggleImageCaption', 'imageTextAlternative', 'ckboxImageEdit' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Refer to the [image installation](#ckeditor5/latest/features/images/images-installation.html) guide for more details on configuring the features available in the toolbar and to the `#image-toolbar` section of the `Update to 29.x` guide in the [updating from older versions guide](#ckeditor5/latest/updating/guides/updating-from-older-versions.html), as important changes were introduced in that version. You can also check the [editor toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) guide.

See the common API of image-related features such as [ImageStyle](../../api/module%5Fimage%5Fimagestyle-ImageStyle.html), [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html), and [LinkImage](../../api/module%5Flink%5Flinkimage-LinkImage.html) to learn more about available image toolbar buttons.

<a id="ckeditor5/latest/features/images/images-overview.html--image-width-and-height-attributes">

### Image `width` and `height` attributes

Starting with v40.0.0, the image’s `width` and `height` attributes are retained by the editor when it is loaded. Adding them is done to ensure that the image dimensions ratio is properly kept when an image is styled or aligned and that it always looks like it should, rather than forcing the image size within the content. This ensures high-quality output.

The attributes are now handled as follows:

* Upon [uploading an image file](#ckeditor5/latest/features/images/image-upload/image-upload.html) or [inserting it](#ckeditor5/latest/features/images/images-inserting.html) into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. The editor then adds these properties to the markup, just like the [text alternative tag](#ckeditor5/latest/features/images/images-text-alternative.html).
* If the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten.
* The editor will not change already existing content. It means, loading HTML (that is `setData`) with images does not set up these attributes.
* Changes to an image (such as resize, etc.) will trigger the creation of those attributes. These attributes are crucial to proper content handling, and actions on a current image that does not have these improve this image’s markup.
* The `aspect-ratio` attribute has been added to the image’s properties to handle situations when the file is resized or scaled with a tweaked aspect ratio.

These image properties can be further controlled via CSS styles. If you need to crop, resize, rotate, or mirror flip your images, you can use the [CKBox asset manager](#ckeditor5/latest/features/file-management/ckbox.html) to achieve that.

<a id="ckeditor5/latest/features/images/images-overview.html--typing-around-images">

### Typing around images

To type before or after an image easily, select the image, then press the Arrow key (← or →) once, depending on where you want to add content – before or after respectively. The image becomes no longer selected and whatever text you type will appear in the desired position.

You can also use the **Insert paragraph** handles on the bottom or top edge of the selected image to add a paragraph below or above the image, respectively.

<a id="ckeditor5/latest/features/images/images-overview.html--image-editing">

### Image editing

While the image feature does not provide native image editing support, the [CKBox](#ckeditor5/latest/features/file-management/ckbox.html) and Uploadcare [features/uploadcare](#ckeditor5/latest/features/file-management/uploadcare.html) premium features provide [editing capabilities](#ckeditor5/latest/features/images/images-image-optimizer.html) such as cropping to presets, flipping, or rotating.

<a id="ckeditor5/latest/features/images/images-overview.html--common-api">

### Common API

The `Image` plugin registers:

* The [insertImage](../../api/module%5Fimage%5Fimage%5Finsertimagecommand-InsertImageCommand.html) command (alias: `imageInsert`).
* The [insertImage](../../api/module%5Fimage%5Fimageconfig-ImageInsertConfig.html) dropdown component (to use in the toolbar).

<a id="ckeditor5/latest/features/images/images-overview.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-resizing.html">source file: "ckeditor5/latest/features/images/images-resizing.html"</a>

## Resizing images

The image resize feature lets you change the width of images in your content. It is implemented by the [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html) plugin.

<a id="ckeditor5/latest/features/images/images-resizing.html--methods-to-resize-images">

### Methods to resize images

The editor offers different ways to resize images either by using “resize handles” or by using dedicated UI components – either a dropdown or standalone buttons.

The [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html) plugin enables the four resize handles displayed over the selected image. The user can resize the image by dragging them. You can configure the feature to use either percentage (default) or pixel values.

The plugin also gives you the ability to change the size of the image through the on-click image toolbar. You can set an optional static configuration with [resizeOptions](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeOptions) and choose whether you want to use a dropdown or a set of standalone buttons.

<a id="ckeditor5/latest/features/images/images-resizing.html--using-resize-handles">

#### Using resize handles

In this case, you can resize an image by dragging square handles displayed in each of its corners. After you enable image resizing, this option does not require any additional configuration.

Use the corner handles to resize the image and adjust it to the text as needed. You can also use the alignment options from the image toolbar  to achieve the desired effect.

Images can also be pre-resized using styling, as shown below (the last three images are hard-set to 28% for visual consistency).

You can configure resizing images by handles in two different ways in the CKEditor 5 WYSIWYG editor:

* By installing the [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html) plugin. It contains **all** needed features (`ImageResizeEditing`, `ImageResizeHandles`, `ImageResizeButtons`) as described in the [installation](#ckeditor5/latest/features/images/images-resizing.html--installation) of this guide.
* By installing the combination of [ImageResizeEditing](../../api/module%5Fimage%5Fimageresize%5Fimageresizeediting-ImageResizeEditing.html) and [ImageResizeHandles](../../api/module%5Fimage%5Fimageresize%5Fimageresizehandles-ImageResizeHandles.html) plugins. This will not load the unnecessary `ImageResizeButtons` plugin:

Both ways enable resize handles by default.

<a id="ckeditor5/latest/features/images/images-resizing.html--using-resize-dropdown">

#### Using resize dropdown

In this case, the user can choose from a set of predefined options. You can display these options as a dropdown in the image toolbar available after the user clicks the image.

To use this option, you need to [enable image resizing](#ckeditor5/latest/features/images/images-resizing.html--installation) and configure the available [resize options](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeOptions). Then add the dropdown to the image toolbar configuration.

```
const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            label: 'Original'
        },
        {
            name: 'resizeImage:custom',
            label: 'Custom',
            value: 'custom'
        },
        {
            name: 'resizeImage:40',
            value: '40',
            label: '40%'
        },
        {
            name: 'resizeImage:60',
            value: '60',
            label: '60%'
        }
    ],
    toolbar: [ 'resizeImage', /* ... */ ]
}

```

Try out the live demo of the resize dropdown  available in the image toolbar:

<a id="ckeditor5/latest/features/images/images-resizing.html--using-standalone-resize-buttons">

#### Using standalone resize buttons

In this case, the resize options are displayed as separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.

To use this option, you need to [enable image resizing](#ckeditor5/latest/features/images/images-resizing.html--installation) and configure the available [resize options](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeOptions). Then add appropriate buttons to the image toolbar configuration.

```
const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            icon: 'original'
        },
        {
            name: 'resizeImage:custom',
            value: 'custom',
            icon: 'custom'
        },
        {
            name: 'resizeImage:50',
            value: '50',
            icon: 'medium'
        },
        {
            name: 'resizeImage:75',
            value: '75',
            icon: 'large'
        }
    ],
    toolbar: [
        'resizeImage:50',
        'resizeImage:75',
        'resizeImage:original',
        'resizeImage:custom',
        // More toolbar options.
        // ...
    ]
}

```

Try out the live demo of the individual resize buttons  available in the image toolbar:

<a id="ckeditor5/latest/features/images/images-resizing.html--disabling-image-resize-handles">

### Disabling image resize handles

If you want to configure the editor in such a way that the user can only resize images by buttons, you can do so by omitting the [ImageResizeHandles](../../api/module%5Fimage%5Fimageresize%5Fimageresizehandles-ImageResizeHandles.html) plugin.

As a result, your plugin setup should look like this: `plugins: [ 'ImageResizeEditing', 'ImageResizeButtons', /* ... */ ]` as opposed to `plugins: [ 'ImageResize', /* ... */ ]`.

This will enable the image resize feature only through the chosen UI: either a [dropdown](#ckeditor5/latest/features/images/images-resizing.html--using-resize-dropdown) or [standalone buttons](#ckeditor5/latest/features/images/images-resizing.html--using-standalone-resize-buttons) in the image toolbar.

<a id="ckeditor5/latest/features/images/images-resizing.html--markup-and-styling">

### Markup and styling

When you resize an image, the inline `width` style is used and the editor assigns the `image_resized` class to the `<figure>` element:

```
<figure class="image image_resized" style="width: 75%;">
    <img src="..." alt="...">
</figure>

```

The `image_resized` class is used to disable `max-width` assigned by the [image styles](#ckeditor5/latest/features/images/images-styles.html) if one is applied to this image. For instance, the “side image” style is defined like this:

```
.ck-content .image-style-side {
    max-width: 50%;
    float: right;
    margin-left: var(--ck-image-style-spacing);
}

```

And the `max-width` gets overridden by the following rule:

```
.ck-content .image.image_resized {
    max-width: 100%;
}

```

Another concern when styling resized images is that by default, CKEditor 5 uses `display: table` on `<figure class="image">` elements to make it take up the size of the `<img>` element inside it. Unfortunately, [browsers do not yet support using max-width and width on the same element if it is styled with display: table](https://stackoverflow.com/questions/4019604/chrome-safari-ignoring-max-width-in-table/14420691#14420691). Therefore, `display: block` needs to be used when resizing the image:

```
.ck-content .image.image_resized {
    display: block;
    box-sizing: border-box;
}

.ck-content .image.image_resized img {
    width: 100%;
}

.ck-content .image.image_resized > figcaption {
    display: block;
}

```

<a id="ckeditor5/latest/features/images/images-resizing.html--using-pixel-values-instead-of-percentage-width">

### Using pixel values instead of percentage width

Using percentage widths ensures that the content stays responsive when displayed in places other than the WYSIWYG editor. When the user makes an image take up, for example, 60% of the content’s width in the editor, if you ever change the width of the target page (where this content is displayed), the image will still take up 60% of that space. The same is true if the page is responsive and adjusts to the viewport’s width.

If you configured the editor to use pixel values, the image could take up, for example, too much space after you introduced a new layout for your website.

However, there are cases where you may prefer pixel values. You can thus configure the editor to use them by setting the [config.image.resizeUnit](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeUnit) option:

```
ClassicEditor
    .create( {
        image: {
            resizeUnit: 'px',
            resizeOptions: [
                {
                    name: 'resizeImage:original',
                    label: 'Original',
                    value: null
                },
                {
                    name: 'resizeImage:custom',
                    label: 'Custom',
                    value: 'custom'
                },
                {
                    name: 'resizeImage:100',
                    label: '100px',
                    value: '100'
                },
                {
                    name: 'resizeImage:200',
                    label: '200px',
                    value: '200'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The following demo uses CSS to set up the fixed image aspect ratio, so a 200px wide image automatically gets the same height.

<a id="ckeditor5/latest/features/images/images-resizing.html--aspect-ratio-css"> 

```
.ck.ck-content .image {
    position: relative;
}
.ck.ck-content .image img {
    position: absolute;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
    border-radius: 50%;
}
.ck.ck-content .image::before {
    content: '';
    padding-top: 100%;
    display: block;
}

```

Check out the difference in the live demo below:

<a id="ckeditor5/latest/features/images/images-resizing.html--image-optimization-and-responsive-images">

### Image optimization and responsive images

When using the [CKBox file manager](#ckeditor5/latest/features/file-management/ckbox.html) service, it produces sets of resized, optimized images. The users can invoke these resized versions if needed. To learn more about these capabilities, refer to the [responsive images](#ckeditor5/latest/features/images/images-responsive.html) guide and the [CKBox conversion](#ckbox/latest/features/images/conversion.html) guide.

<a id="ckeditor5/latest/features/images/images-resizing.html--installation">

### Installation

To enable it you need to install the [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html) plugin, which contains **all** needed features (`ImageResizeEditing`, `ImageResizeHandles`, `ImageResizeButtons`):

<a id="ckeditor5/latest/features/images/images-resizing.html--common-api">

### Common API

The [ImageResize](../../api/module%5Fimage%5Fimageresize-ImageResize.html) plugin registers:

* Image resize buttons (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['resizeImage' command](../../api/module%5Fimage%5Fimageresize%5Fresizeimagecommand-ResizeImageCommand.html) that accepts the target width.

<a id="ckeditor5/latest/features/images/images-resizing.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-responsive.html">source file: "ckeditor5/latest/features/images/images-responsive.html"</a>

## Responsive images

The ability to have responsive images in the rich-text editor content is a great modern feature provided by the [CKBox asset manager](#ckeditor5/latest/features/file-management/ckbox.html). With a single image upload, several optimized versions of that image are created, each for a different size of the display. The CKBox feature produces a `<picture>` element with a set of optimized images. The browser will automatically load the image with the dimensions most suitable for the presented page resolution, which makes the image load much faster and saves bandwidth.

<a id="ckeditor5/latest/features/images/images-responsive.html--demo">

### Demo

Observe the responsive image in the demo. You can also add another one with the CKBox toolbar button . Resize your browser window to change the editor viewport and observe how the editor automatically serves the size-adjusted, optimized image.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-responsive.html--why-responsive-images">

### Why responsive images?

Responsive images have two main advantages over “traditional” image delivery:

* **They save the data transfer**. There are countless device and screen size combinations that can be used to display images in your application (smartphones, tablets, laptops, etc.). You do not need to serve the same full–scale images to all of them, though. Using CKBox guarantees only the particular size variant corresponding to the user’s screen size is served, minimizing the amount of data transferred to the client. For large images, this can save up to 90% of the transferred data.
* **They load faster**. Because only the image matching the size of the screen is transferred, in most cases it can be loaded and displayed much faster than a “regular” full–scale image. The faster it loads, the sooner the users can see it, which greatly improves the user experience of your application. You no longer need to wait for ages for high–resolution photos to load on a tiny smartphone screen.
* **Accessibility**. By catering to different user devices, you may better address the users’ different needs. Paired with the [text alternative](#ckeditor5/latest/features/images/images-text-alternative.html) it makes your content more accessible.

<a id="ckeditor5/latest/features/images/images-responsive.html--responsive-images-in-the-markup">

### Responsive images in the markup

The image appears in the editor content as a `<picture>` element. The `<picture>` element contains the original `<img>` and the `<source>` element, which defines alternative versions of images using the `srcset` attribute.

The `srcset` attribute specifies the image variants dedicated to the various screen sizes for the web browser to choose from (360px, 720px, 1080px, 1440px, etc.).

For instance, the `image.jgeg` file uploaded by the user will have the following markup:

```
    <picture>
        <source srcset="https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/160.webp 160w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/320.webp 320w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/480.webp 480w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/640.webp 640w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/800.webp 800w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/960.webp 960w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/1120.webp 1120w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/1280.webp 1280w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/1440.webp 1440w,
        https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/1600.webp 1600w"
        sizes="(max-width: 1600px) 100vw, 1600px"
        type="image/webp">
        <img src="https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/1600.jpeg" alt="Snowdrop" data-ckbox-resource-id="M0tgMczsDphw">
    </picture>

```

The variety of the image sizes in the `srcset` attribute allows the web browser to choose the best one for the particular screen size. As a result, it loads faster and with less data transferred. Read the [CKBox responsive images](#ckbox/latest/features/images/responsive-images.html) guide to learn how are the intermediate file sizes calculated.

Regardless of the original file format, the responsive versions will be served as `.webp`.

<a id="ckeditor5/latest/features/images/images-responsive.html--installation">

### Installation

For detailed information on how to configure and use CKBox, please refer to the [CKBox file manager](#ckeditor5/latest/features/file-management/ckbox.html--installation) installation guide.

<a id="ckeditor5/latest/features/images/images-styles.html">source file: "ckeditor5/latest/features/images/images-styles.html"</a>

## Image styles

The image styles feature lets you adjust the appearance of images. It works by applying CSS classes to images or changing their type from inline to block or vice versa.

<a id="ckeditor5/latest/features/images/images-styles.html--overview">

### Overview

This package allows for adjusting the image appearance by:

* **Applying CSS classes** – Adding a particular [predefined](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles) or [custom](#ckeditor5/latest/features/images/images-styles.html--configuring-the-styles) CSS class or removing any style-related CSS class.
* **Managing the HTML representation** by changing the image type from inline to block and vice versa. Applying a style may change the type of the image, depending on the configuration of the style.

<a id="ckeditor5/latest/features/images/images-styles.html--image-classes">

#### Image classes

The styles applied to the image can either add the style-related class or remove it. This behavior depends on the particular configuration of the [ImageStyleOptionDefinition](../../api/module%5Fimage%5Fimageconfig-ImageStyleOptionDefinition.html). Only the definition with the [isDefault](../../api/module%5Fimage%5Fimageconfig-ImageStyleOptionDefinition.html#member-isDefault) flag set to true will remove any applied image style-related class.

<a id="ckeditor5/latest/features/images/images-styles.html--inline-and-block-images">

#### Inline and block images

You can display images in the editor as either inline or block.

The inline-type images are represented as inline HTML elements. You can insert them in the middle of a paragraph or in a link just like regular text. The HTML representation of the inline image looks like this:

* `<span class=”image-style-class”><img></img></span>` in the editable.
* `<img class=”image-style-class”></img>` in the HTML content retrieved by the [getData()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method.

Block-type images can be inserted only between other blocks like paragraphs, tables, or media. The HTML representation of the block image looks like this:

* `<figure class=”image image-style-class”><img></img></figure>`.

**Switching between these two types of images can be executed by applying or removing a style from the image**. Each of the defined style options provides a list of the image types that it can apply to. Applying a style may change the type of the image, depending on the configuration of the style.

When you insert a new image, the editor will, by default, choose the optimal image type based on the context of the insertion (for example, the current selection/position and [availability of plugins](#ckeditor5/latest/features/images/images-installation.html--inline-and-block-images)). You can control the default type of the newly inserted image using the [image.insert.type configuration](../../api/module%5Fimage%5Fimageconfig-ImageInsertConfig.html#member-type).

<a id="ckeditor5/latest/features/images/images-styles.html--ui">

### UI

You can apply a style by using one of the toolbar buttons created by the `ImageStyle` plugin. Each of the defined styles (both [default](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles) and [custom](#ckeditor5/latest/features/images/images-styles.html--configuring-the-styles)) will be registered under the name `imageStyle:image-style-name` in the [ComponentFactory](../../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html). You can then add it to the image or main toolbar by referencing this name.

The default image toolbar has its standard configuration already set.

* The default UI of the classic, inline, balloon, and balloon block editor types consists of a set of buttons to apply the [semantical styles](#ckeditor5/latest/features/images/images-styles.html--semantical-styles) to support creating structured content. [**See a live example**](#ckeditor5/latest/features/images/images-styles.html--semantical-example).
* The document editor type UI uses several buttons for applying [presentational styles](#ckeditor5/latest/features/images/images-styles.html--presentational-styles) and also uses the [semantical styles](#ckeditor5/latest/features/images/images-styles.html--semantical-styles) to reset the image appearance to default. [**See a live example**](#ckeditor5/latest/features/images/images-styles.html--presentational-example).

You can also create a completely custom image styles UI, setting your icons and tooltips, and grouping the image style buttons into [custom dropdowns](../../api/module%5Fimage%5Fimageconfig-ImageStyleDropdownDefinition.html). Read more about it in the [**configuring the styles**](#ckeditor5/latest/features/images/images-styles.html--configuring-the-styles) section of this guide.

<a id="ckeditor5/latest/features/images/images-styles.html--approaches-to-styling-images">

### Approaches to styling images

CKEditor 5 offers two basic approaches to styling the images:

* A particular style can define the image type, so you can style it, for example, as an avatar, a banner, or an emoticon. It will be called a [“semantical style”](#ckeditor5/latest/features/images/images-styles.html--semantical-styles) since it refers to the purpose of the particular image.
* Sometimes the user should be able to granularly control how an image is presented thanks to the ability to set the size and alignment separately and completely arbitrarily. The style that defines the image alignment will be called a [“presentational”](#ckeditor5/latest/features/images/images-styles.html--presentational-styles) one since it refers to the appearance of the image.

<a id="ckeditor5/latest/features/images/images-styles.html--semantical-styles">

#### Semantical styles

A semantical style lets the user choose from predefined appearances of the images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. Check the list of the available semantical styles in the [table](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles) below. Semantical styles give the integrator the ability to put a wide range of predefined image appearances at the user’s disposal. This gives the developer control over how the users style their images and makes the user’s life easier by setting many properties at once.

Most of the editor types support editing structured content. This requires passing the control over the possible image appearances to the developer. We thus introduce a UI containing a set of buttons applying the semantical styles (taken from the [default styles](#ckeditor5/latest/features/images/images-styles.html--styles-table) listed below).

The example below shows an editor with such a basic configuration. There are three types of images:

* **A block image**  – A representation of a block image with no style-related CSS class.
* **An inline image**  – A representation of an inline image with no style-related CSS class.
* **A side image**  – A semantical style with the `image-style-side` CSS class applied to it

You can change the style of an individual image using the contextual toolbar that opens after clicking the image.

<a id="ckeditor5/latest/features/images/images-styles.html--semantical-example">

<a id="ckeditor5/latest/features/images/images-styles.html--presentational-styles">

#### Presentational styles

Presentational styles do not relate to any special meaning of the content. They directly control the visual aspect of an image. The default available presentational styles determine the image alignment behavior. Check the list of the available semantical styles in the [table](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles) below.

The example editor below uses predefined presentational image styles represented by buttons grouped in the dropdowns according to the way the image is displayed in the document:

* **Inline images**  – Displayed inside a line of text. It is the default style for the inline images and it does not apply any CSS class to the image.
* **Images wrapped with text**  – These are the images with the CSS `float` property. They can be either in the inline or block mode. To keep the HTML output valid, the block images (wrapped with the `<figure>` tags) can only be placed before or after paragraphs, not in the middle of them. It contains the following image styles:  
  * `'align-left'` ,
  * `'align-right'` .
* **Images placed between the paragraphs**  – Block images without the CSS `float` property. It contains the following image styles:  
  * `'align-block-left'` ,
  * `'align-block-right'` ,
  * `'block'`  – This style is the default one for block images and it does not apply any CSS class to the image.

You can change the style of an individual image using the contextual toolbar invoked after you click an image.

The example is also configured to use the [image resize feature](#ckeditor5/latest/features/images/images-resizing.html) with three [resize options](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeOptions) available: `'resizeImage:original'`, `'resizeImage:50'`, and `'resizeImage:75'`. They allow you to set the image width in the editor to the original image size (up to 100% of the editor window width), 50%, and 75%. You can also use the resize handles to set a custom size of the image.

See the result below:

<a id="ckeditor5/latest/features/images/images-styles.html--presentational-example">

This set of buttons and styles is available by default in the document editor and does not require any additional customization:

```
import { DecoupledEditor } from 'ckeditor5';

DecoupledEditor.create( {
    root: {
        element: document.querySelector( '#editor' )
    }
} ).then( /* ... */ );

```

<a id="ckeditor5/latest/features/images/images-styles.html--configuring-the-styles">

### Configuring the styles

There are three ways of defining the image styles in the editor configuration:

* Using one of the predefined [default styles](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles).
* Modifying one of the styles mentioned above. You can change the class it applies to the image, the icon, the tooltip, and the supported image type.
* Defining a completely custom image style.

<a id="ckeditor5/latest/features/images/images-styles.html--demo">

#### Demo

The editor example below shows what you can achieve by customizing the visual representation of images and the UI for setting image styles (icons, tooltips, and dropdowns).

This editor uses custom image styles, custom image toolbar configuration with [declarative dropdowns](../../api/module%5Fimage%5Fimageconfig-ImageStyleDropdownDefinition.html), and some modified [default styles](#ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles). You can find some more examples of using and modifying these styles in the [config.image.styles](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-styles) API documentation.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        image: {
            styles: {
                // Defining custom styling options for the images.
                options: [ {
                    name: 'side',
                    icon: sideIcon,
                    title: 'Side image',
                    className: 'image-side',
                    modelElements: [ 'imageBlock' ]
                }, {
                    name: 'margin-left',
                    icon: leftIcon,
                    title: 'Image on left margin',
                    className: 'image-margin-left',
                    modelElements: [ 'imageInline' ]
                }, {
                    name: 'margin-right',
                    icon: rightIcon,
                    title: 'Image on right margin',
                    className: 'image-margin-right',
                    modelElements: [ 'imageInline' ]
                },
                // Modifying icons and titles of the default inline and
                // block image styles to reflect its real appearance.
                {
                    name: 'inline',
                    icon: inlineIcon
                }, {
                    name: 'block',
                    title: 'Centered image',
                    icon: centerIcon
                } ]
            },
            toolbar: [ {
                // Grouping the buttons for the icon-like image styling
                // into one dropdown.
                name: 'imageStyle:icons',
                title: 'Alignment',
                items: [
                    'imageStyle:margin-left',
                    'imageStyle:margin-right',
                    'imageStyle:inline'
                ],
                defaultItem: 'imageStyle:margin-left'
            }, {
                // Grouping the buttons for the regular
                // picture-like image styling into one dropdown.
                name: 'imageStyle:pictures',
                title: 'Style',
                items: [ 'imageStyle:block', 'imageStyle:side' ],
                defaultItem: 'imageStyle:block'
            }, '|', 'toggleImageCaption', 'linkImage'
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

It also applies multiple CSS rules to not only display custom image styles (the `'image-margin-right'`, `'image-margin-left'` and `'image-side'` classes) properly, but also to provide the default [content styles](#ckeditor5/latest/getting-started/setup/css.html), so the appearance of headers, paragraphs, links, captions and newly inserted images is consistent.

The most important rules regarding the image styling are presented below. You can see the complete content style sheet [here](https://github.com/ckeditor/ckeditor5/blob/a95554244e9fc71af5aa9e53c6841f114c6d2483/packages/ckeditor5-image/docs/%5Fsnippets/features/image-semantical-style-custom.html).

```
/* Defining the default content styles for the block images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image {
    margin-top: 50px;
    margin-bottom: 50px;
}
.ck-content .image img {
    border-radius: 50%;
    width: 180px;
    height: 180px;
    object-fit: cover;
    filter: grayscale(100%) brightness(70%);
    box-shadow: 10px 10px 30px #00000078;
}
.ck-content .image::before {
    content: '';
    width: 100%;
    height: 100%;
    background-color: #1138b0;
    top: 5%;
    left: 5%;
    position: absolute;
    border-radius: 50%;
}
.ck-content .image::after {
    content: '';
    width: 200%;
    height: 200%;
    background-image: url(../../assets/img/image-context.svg);
    background-size: contain;
    background-repeat: no-repeat;
    position: absolute;
    top: -60%;
    pointer-events: none;
    left: -60%;
}

/* Defining the default content styles for the inline images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image-inline {
    margin: 0 4px;
    vertical-align: middle;
    border-radius: 12px;
}
.ck-content .image-inline img {
    width: 24px;
    max-height: 24px;
    min-height: 24px;
    filter: grayscale(100%);
}

/* Defining the custom content styles for the images
placed on the side of the editing area. */
.ck-content .image.image-side {
    float: right;
    margin-right: -200px;
    margin-left: 50px;
    margin-top: -50px;
}
.ck-content .image.image-side img {
    width: 360px;
    height: 360px;
}

/* Defining the custom content styles for the images
placed on the editor margins. */
.ck-content .image-inline.image-margin-left,
.ck-content .image-inline.image-margin-right {
    position: absolute;
    margin: 0;
    top: auto;
}
.ck-content .image-inline.image-margin-left {
    left: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-right {
    right: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-left img,
.ck-content .image-inline.image-margin-right img {
    filter: none;
}

/* Defining the custom content styles for the image captions. */
.ck-content .image > figcaption {
    z-index: 1;
    position: absolute;
    bottom: 20px;
    left: -20px;
    font-style: italic;
    border-radius: 41px;
    background-color: #ffffffe8;
    color: #1138b0;
    padding: 5px 12px;
    font-size: 13px;
    box-shadow: 0 0 18px #1a1a1a26
}

```

<a id="ckeditor5/latest/features/images/images-styles.html--ready-to-use-styles">

#### Ready-to-use styles

The `ImageStyle` plugin provides a set of default styles depending on the loaded plugins. The table below presents the availability of these styles and the image behavior caused by an application of a particular style.

| Style name        | Required plugins | Converts to | Applies class                       | Type           |
| ----------------- | ---------------- | ----------- | ----------------------------------- | -------------- |
| "block"           | ImageBlock       | block       | removes all classes (default style) | semantical     |
| "inline"          | ImageInline      | inline      | removes all classes (default style) | semantical     |
| "side"            | ImageBlock       | block       | image-style-side                    | semantical     |
| "alignLeft"       | any              | \-          | image-style-align-left              | presentational |
| "alignRight"      | any              | \-          | image-style-align-right             | presentational |
| "alignBlockLeft"  | ImageBlock       | block       | image-style-align-block-left        | presentational |
| "alignBlockRight" | ImageBlock       | block       | image-style-align-block-right       | presentational |
| "alignCenter"     | ImageBlock       | block       | image-style-align-center            | presentational |

<a id="ckeditor5/latest/features/images/images-styles.html--installation">

### Installation

Check out the [image feature installation guide](#ckeditor5/latest/features/images/images-installation.html) to learn how to enable this feature.

<a id="ckeditor5/latest/features/images/images-styles.html--common-api">

### Common API

The [ImageStyle](../../api/module%5Fimage%5Fimagestyle-ImageStyle.html) plugin registers:

* A button for each defined style, for example: `'imageStyle:block'` and `'imageStyle:side'` (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['imageStyle' command](../../api/module%5Fimage%5Fimagestyle%5Fimagestylecommand-ImageStyleCommand.html). It accepts a value based on the [image.styles](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-styles) configuration option (for example, `'block'` and `'side'`):  
```  
editor.execute( 'imageStyle', { value: 'side' } );  
```

<a id="ckeditor5/latest/features/images/images-styles.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/images/images-text-alternative.html">source file: "ckeditor5/latest/features/images/images-text-alternative.html"</a>

## Image text alternative

Image text alternative (the `alt` attribute) helps screen reader users navigate and understand the document. It also provides meaningful image descriptions to search engine crawlers.

<a id="ckeditor5/latest/features/images/images-text-alternative.html--demo">

### Demo

The editor below has the base image feature enabled. Click any of the images and use the contextual image toolbar  to edit the text alternative.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/images/images-text-alternative.html--additional-feature-information">

### Additional feature information

The `alt` attribute is essential for both accessibility and [SEO](https://en.wikipedia.org/wiki/Search%5Fengine%5Foptimization).

CKEditor 5 provides support for alternate image text using the [ImageTextAlternative](../../api/module%5Fimage%5Fimagetextalternative-ImageTextAlternative.html) plugin. The `alt` attribute is supported by both block and inline images in the editor output data:

```
<!-- Block image markup -->
<figure class="image">
    <img src="..." alt="Description of an image">
    <figcaption>...</figcaption>
</figure>

<!-- Inline image in a paragraph -->
<p>Some text followed by an image <img src="..." alt="Description of an image">.</p>

```

<a id="ckeditor5/latest/features/images/images-text-alternative.html--utilizing-ckbox-to-manage-text-alternatives">

#### Utilizing CKBox to manage text alternatives

When using the [CKBox file manager](#ckeditor5/latest/features/file-management/ckbox.html), you can utilize its [metadata management tools](https://ckeditor.com/docs/ckbox/latest/features/file-management/assets/metadata.html#description) to set or change the text alternative. CKBox automatically adds the metadata `description` to the `alt` tag.

<a id="ckeditor5/latest/features/images/images-text-alternative.html--installation">

### Installation

Check out the [image features installation guide](#ckeditor5/latest/features/images/images-installation.html) to learn how to enable this feature.

<a id="ckeditor5/latest/features/images/images-text-alternative.html--common-api">

### Common API

The [ImageTextAlternative](../../api/module%5Fimage%5Fimagetextalternative-ImageTextAlternative.html) plugin registers:

* The `'imageTextAlternative'` button (to use in the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)).
* The ['imageTextAlternative' command](../../api/module%5Fimage%5Fimagetextalternative%5Fimagetextalternativecommand-ImageTextAlternativeCommand.html).

<a id="ckeditor5/latest/features/images/images-text-alternative.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image>.

<a id="ckeditor5/latest/features/indent.html">source file: "ckeditor5/latest/features/indent.html"</a>

## Block indentation

The block indentation feature lets you set indentation for text blocks such as paragraphs, headings, or lists. This way you can visually distinguish parts of your content.

<a id="ckeditor5/latest/features/indent.html--demo">

### Demo

Use the indent  or outdent  toolbar buttons in the editor below to change the indentation level. Try this on different elements: paragraphs, headings, and list items.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/indent.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/indent.html--configuring-the-block-indentation-feature">

### Configuring the block indentation feature

This feature offers a few configuration options that can be used to adjust the text block indentation behavior. It is implemented by three plugins: [Indent](../api/module%5Findent%5Findent-Indent.html), [IndentBlock](../api/module%5Findent%5Findentblock-IndentBlock.html) and [List](../api/module%5Flist%5Flist-List.html).

List block indentation uses the same configuration as block indentation for paragraphs and headings. The default indentation step is `40px`. You can change it through the `indentBlock` configuration option, including switching to CSS classes.

<a id="ckeditor5/latest/features/indent.html--using-offset-and-unit">

#### Using offset and unit

By default, the block indentation feature increases or decreases the current indentation by the given offset, using the given unit.

The rich-text editor from the [demo](#ckeditor5/latest/features/indent.html--demo) section above uses the default configuration, which defines a `40px` indentation step.

You can change that value to, for example, `1em`:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        indentBlock: {
            offset: 1,
            unit: 'em'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/indent.html--using-css-classes">

#### Using CSS classes

If you want more semantics in your content, use CSS classes instead of fixed indentation units. You can then adjust the levels in the style sheets of your application whenever you want.

Here is how you can configure the block indentation feature to set indentation by applying one of the defined CSS classes:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        indentBlock: {
            classes: [
                'custom-block-indent-a', // First step - smallest indentation.
                'custom-block-indent-b',
                'custom-block-indent-c'  // Last step - biggest indentation.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Using classes instead of fixed units (`px` or `em`) has another advantage – you retain control over what indentation levels are used in the documents. For instance, you can limit indentation to 2 or 3 different levels and there is no way the users can go beyond that. In the example above, the `.custom-block-indent-c` class level is the maximum allowed indentation value. This should help keep your content clean and predictable.

In this configuration, the WYSIWYG editor will restrict indentation levels to the set of provided classes. The class with the last index in the array has the biggest indentation.

In the demo below the CSS classes are defined as follows:

```
.custom-block-indent-a {
    margin-left: 10%;
}

.custom-block-indent-b {
    margin-left: 20%;
}

.custom-block-indent-c {
    margin-left: 30%;
}

```

<a id="ckeditor5/latest/features/indent.html--indenting-lists">

### Indenting lists

Besides controlling text block indentation, the same set of buttons (`outdent`, `indent`) allows for indenting list items (nesting them).

This mechanism is completely transparent to the user. From the code perspective, the buttons are implemented by the [Indent](../api/module%5Findent%5Findent-Indent.html) plugin, but neither these buttons nor the respective commands implement any functionality by default.

The target behavior comes from two other plugins:

* [IndentBlock](../api/module%5Findent%5Findentblock-IndentBlock.html) – The indent block feature controls the indentation of elements such as paragraphs and headings.
* [List](../api/module%5Flist%5Flist-List.html) – The list feature implements the indentation (nesting) of lists.

This means that if you want to allow indenting lists only, you can do that by loading the `Indent` and `List` plugins only. If you want the full behavior – nesting list items, block indentation of paragraphs and headings, and visual block indentation of lists – you need to load all three plugins: `Indent`, `IndentBlock`, and `List`.

When all three plugins are loaded, the editor also supports applying visual block indentation to list containers (`<ol>`, `<ul>`) and list items (`<li>`). This works the same way as block indentation for paragraphs and headings – it adds a `margin-left` style (or a CSS class, depending on the [configuration](#ckeditor5/latest/features/indent.html--configuring-the-block-indentation-feature)) to the list elements. The editor understands `margin-left` styles on all these elements during data loading, across all list types (numbered, bulleted, to-do, multi-level) and at all nesting levels. Negative indentation values (such as `-50px`) are also accepted during data loading.

<a id="ckeditor5/latest/features/indent.html--indenting-list-containers">

#### Indenting list containers

Only the topmost list in the content can be indented or outdented. The selection must be at the start of the list (collapsed or non-collapsed). Use one of the following methods:

* Press Tab to indent or Shift+Tab to outdent the list. The indentation changes in steps (by default, `40px`).
* Use the indent  and outdent  toolbar buttons. The indentation also changes in steps.

It is not possible to outdent a list below `0` as negative values cannot be set through the editor UI. If a list with a negative indentation value was loaded into the editor, indenting it resets the value to `0` in a single step.

You can also remove the list indentation using the [remove format](#ckeditor5/latest/features/remove-format.html) feature, which removes the indentation attribute in one step.

<a id="ckeditor5/latest/features/indent.html--indenting-list-items">

#### Indenting list items

List items cannot be indented through the editor UI. However, indentation values on `<li>` elements are recognized during data loading.

A list item’s indentation can only be reset in a single step by:

* Using the indent  button (if the value is negative) or the outdent  button (if the value is positive).
* Using the [remove format](#ckeditor5/latest/features/remove-format.html) feature.

The selection must be set inside a list item (or span multiple list items) for these actions to work.

<a id="ckeditor5/latest/features/indent.html--related-features">

### Related features

Here are some CKEditor 5 features that may help structure your content better:

* [Block quote](#ckeditor5/latest/features/block-quote.html) – Include block quotations or pull quotes in your rich-text content.
* [Headings](#ckeditor5/latest/features/headings.html) – Divide your content into sections.
* [Code block](#ckeditor5/latest/features/code-blocks.html) – Insert longer, multiline code listings.
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Because it does matter whether the content is left, right, centered, or justified.

<a id="ckeditor5/latest/features/indent.html--common-api">

### Common API

The [Indent](../api/module%5Findent%5Findent-Indent.html) plugin registers the following components:

* The `'indent'` command.  
This command does not implement any indentation behavior by itself. It executes either `indentBlock` (described below) or `indentList`, depending on which of these commands is enabled.  
Read more in the [Indenting lists](#ckeditor5/latest/features/indent.html--indenting-lists) section above.
* The `'outdent'` command.  
This command does not implement any indentation behavior by itself. It executes either `outdentBlock` (described below) or `outdentList`, depending on which of these commands is enabled.  
Read more in the [Indenting lists](#ckeditor5/latest/features/indent.html--indenting-lists) section above.

The [IndentBlock](../api/module%5Findent%5Findentblock-IndentBlock.html) plugin registers the following components:

* The ['indentBlock'](../api/module%5Findent%5Findentblockcommand-IndentBlockCommand.html) command.  
You can increase the indentation of the text block that contains the selection by:  
```  
editor.execute( 'indentBlock' );  
```
* The ['outdentBlock'](../api/module%5Findent%5Findentblockcommand-IndentBlockCommand.html) command.  
You can decrease the indentation of the text block that contains the selection by:  
```  
editor.execute( 'outdentBlock' );  
```

<a id="ckeditor5/latest/features/indent.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-font>.

<a id="ckeditor5/latest/features/index.html">source file: "ckeditor5/latest/features/index.html"</a>

## CKEditor 5 features overview

CKEditor 5 has many features, and the number is constantly growing. You can find the most recent list of features on the left. In addition to working on new features, we also expand and improve the existing ones. Newly added or meaningfully updated feature guides are marked with a icon. Premium features, which require an additional license to work, have a icon.

<a id="ckeditor5/latest/features/index.html--using-ckeditor-5-features">

### Using CKEditor 5 features

Most of the editor features are accessible from a [highly configurable toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) (in fact, there are [two of those](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar)) offering buttons and dropdowns. Some features also have a dedicated contextual toolbar. You can also execute plenty of actions with [keyboard shortcuts](#ckeditor5/latest/features/accessibility.html). CKEditor 5 offers a dedicated [accessibility help dialog](#ckeditor5/latest/features/accessibility.html--displaying-keyboard-shortcuts-in-the-editor) that displays a list of all available keyboard shortcuts in a dialog. It can be opened by pressing Alt \+ 0 (on Windows) or Option \+ 0 (on macOS) or via toolbar. The entire user interface comes with a [multitude of translations](#ckeditor5/latest/getting-started/setup/ui-language.html) and it supports Right-to-Left (RTL) languages.

<a id="ckeditor5/latest/features/index.html--ckeditor-5-wysiwyg-editor-features-and-functions">

### CKEditor 5 WYSIWYG editor features and functions

CKEditor 5 features cover several functional areas. Listed below are some of the most useful ones.

<a id="ckeditor5/latest/features/index.html--formatting-features">

#### Formatting features

[Basic text styles](#ckeditor5/latest/features/basic-styles.html) include essentials like bold , italics , superscript , and subscript  as well as inline code formatting and more.

The [font feature](#ckeditor5/latest/features/font.html) provides support for using different font families , controlling the font size  as well as font  and background colors .

[Headings](#ckeditor5/latest/features/headings.html)  (with configurable levels and styles) and the [text alignment feature](#ckeditor5/latest/features/text-alignment.html)  help organize the structure of the document.

You can apply most of these formatting options from the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) or on the go, as you type, thanks to the [autoformatting feature](#ckeditor5/latest/features/autoformat.html) that employs Markdown syntax. You can remove them with the [remove format feature](#ckeditor5/latest/features/remove-format.html) .

<a id="ckeditor5/latest/features/index.html--advanced-content-editing">

#### Advanced content editing

Rich text would not be rich without images. You can upload, caption, edit, or style them. You can even paste them straight from the URL with the help of the [image feature](#ckeditor5/latest/features/images/images-overview.html)  and create a responsive design. If that is not enough, [embed media](#ckeditor5/latest/features/media-embed.html)  into your content.

[Links](#ckeditor5/latest/features/link.html)  are an essential feature for online content. You can paste, change, or attribute them.

Provide clear and accessible data using [tables](#ckeditor5/latest/features/tables/tables.html)  (you can even nest them to create advanced layouts), ordered  and unordered [lists](#ckeditor5/latest/features/lists/lists.html)  with various markers to choose from, and [to-do lists](#ckeditor5/latest/features/lists/todo-lists.html) . Use [indents and outdents](#ckeditor5/latest/features/indent.html)  and [block quotes](#ckeditor5/latest/features/block-quote.html)  to structure the content and draw the reader’s attention to it.

Enrich your content further by [embedding HTML code](#ckeditor5/latest/features/html/html-embed.html)  – this one is useful for webmasters. If you need to present code instead of employing it, use the [code block](#ckeditor5/latest/features/code-blocks.html)  that lets you produce code listing with a syntax highlight, too!

<a id="ckeditor5/latest/features/index.html--collaboration">

#### Collaboration

We created the [CKEditor 5 Framework](#ckeditor5/latest/framework/index.html) with [collaboration](#ckeditor5/latest/features/collaboration/collaboration.html) in mind.

All collaboration features manage user data and permissions with the [users API](#ckeditor5/latest/features/collaboration/users.html). [Track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html)  allows the users to follow any changes made to the edited document both asynchronously and in real time. The users accept or reject these changes with a single click from a convenient side panel.

Where tracking changes is not enough, the [comments](#ckeditor5/latest/features/collaboration/comments/comments.html)  come in, offering a perfect collaborative communication platform for writing and editing as a team. When you resolve a discussion, it moves to the comments archive.

Additionally, CKEditor 5 offers the [restricted editing mode](#ckeditor5/latest/features/restricted-editing.html)  where just the selected parts of the content may be edited by some users, based on a permissions system. And when there is a need for even more control, there are the [read-only](#ckeditor5/latest/features/read-only.html) and [comments-only](#ckeditor5/latest/features/collaboration/comments/comments-only-mode.html) modes that let the user access the content, but not edit it.

You can also track the progress and changes done in the content with the [revision history feature](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) . This robust document versioning tool lets you create named versions, compare changes, and restore previous document versions. It tracks all progress – also when many editors work together.

<a id="ckeditor5/latest/features/index.html--document-conversion">

#### Document conversion

If you need to share the document outside your team, use the [export to PDF feature](#ckeditor5/latest/features/converters/export-pdf.html)  to produce industry-standard, portable, cross-platform files.

If you need to work further on the document, choose the [export to Word feature](#ckeditor5/latest/features/converters/export-word.html)  instead – and keep your comments and changes in the resulting document, ready to edit further.

The [pagination feature](#ckeditor5/latest/features/pagination/pagination.html)  complements the exports to ensure all produced documents will always look the way they should.

If you have any documents in the DOCX format, you can convert them into HTML with the [import from Word feature](#ckeditor5/latest/features/converters/import-word/import-word.html) and then continue editing in CKEditor 5.

<a id="ckeditor5/latest/features/index.html--html-and-markdown-output">

#### HTML and Markdown output

The CKEditor 5 WYSIWYG editor by default produces HTML output that you can save into a database. The default output can be also switched to [GitHub-flavored Markdown](#ckeditor5/latest/features/markdown.html) formatted text.

<a id="ckeditor5/latest/features/index.html--other-productivity-features">

#### Other productivity features

The [AI Assistant](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html)  will help you rewrite, edit, or translate the existing content to match your needs, or even come up with a completely new one!

The [word and character counter](#ckeditor5/latest/features/word-count.html) will help you track progress and control the volume of the content.

Use [Markdown syntax](#ckeditor5/latest/features/autoformat.html) to format content on the go to speed up the editing process. Thanks to [automatic text transformations](#ckeditor5/latest/features/text-transformation.html) (also known as autocorrect) and the [spell checker](#ckeditor5/latest/features/spelling-and-grammar-checking.html)  you can ensure everything is correct. Create multi-language documents and correct them on the go with automatic language detection and [text part language](#ckeditor5/latest/features/language.html) feature.

Keep full control of your work. Be safe and never lose anything thanks to the [autosave plugin](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-autosave-plugin). Create and edit content comfortably on larger viewport in the [fullscreen mode](#ckeditor5/latest/features/fullscreen.html) with better access to the UI.

<a id="ckeditor5/latest/features/index.html--customizable-user-experience">

#### Customizable user experience

Work as you like it – choose a user interface approach from several predefined layouts, add features to your preset or remove them with the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). Then tailor the user interface to your needs with a customizable [editor toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html), arranging feature buttons, dropdowns, and other items in whatever way you need.

<a id="ckeditor5/latest/features/index.html--cross-platform-interoperability">

#### Cross-platform interoperability

Do not get stopped by technology differences – CKEditor 5 offers cross-platform interoperability. As a [web-based JavaScript framework](#ckeditor5/latest/framework/index.html) it works in all environments. What is more, you can use documents from other tools: paste content [from Microsoft Office](#ckeditor5/latest/features/pasting/paste-from-office.html) or from [from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) and preserve all formatting.

The editor supports [pasting plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html) and [Markdown-formatted content](#ckeditor5/latest/features/pasting/paste-markdown.html) to inherit the original document structure.

<a id="ckeditor5/latest/features/index.html--backward-feature-compatibility">

### Backward feature compatibility

If you want to migrate from CKEditor 4 to CKEditor 5, check the [migration guide](#ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html).

<a id="ckeditor5/latest/features/index.html--feature-examples">

### Feature examples

We present each rich-text editor feature on a separate page. It includes one or more working demos showcasing a feature along with some customization ideas that you can use in your implementation.

<a id="ckeditor5/latest/features/index.html--looking-for-more">

### Looking for more

The examples mentioned here do not present all features included in CKEditor 5, nor does the list on the left panel. Some end-user features are quite self-explanatory. They are mentioned, for example, in the keyboard shortcuts guide.

CKEditor 5 is in active development and we add new features to it all the time. We also work on expanding and improving the existing ones. If you are missing anything in particular, feel free to [suggest a new feature](https://github.com/ckeditor/ckeditor5/issues/new?labels=type%3Afeature&template=2-feature-request.md) and share your feedback with us. If it has already been reported by someone else, upvote it 👍 to show your support.

<a id="ckeditor5/latest/features/index.html--creating-custom-features">

### Creating custom features

Probably the most exciting features are the ones you can develop on top of CKEditor 5 Framework!

We are gradually enhancing the [CKEditor 5 Framework documentation](#ckeditor5/latest/framework/index.html) together with the [API documentation](../api/index.html), hoping to give you a solid base for [creating custom features](#ckeditor5/latest/framework/tutorials/crash-course/editor.html).

The official add-ons repository for CKEditor 4 reached an impressive number of over 300 add-ons created and published by the community. Now it is time for you to add your contributions to CKEditor 5!

<a id="ckeditor5/latest/features/language.html">source file: "ckeditor5/latest/features/language.html"</a>

## Text part language

The text part language feature lets you mark the language of text fragments. This way browsers and screen readers can correctly interpret parts written in different languages.

<a id="ckeditor5/latest/features/language.html--demo">

### Demo

In the demo below, select a text fragment. Next, use the language toolbar dropdown to choose from predefined languages.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/language.html--additional-feature-information">

### Additional feature information

The text part language feature is especially useful when your content includes text sections written in different text directions, for example, when the whole content is in English but includes some citations in Arabic.

The text part language feature implements the [WCAG 3.1.2 Language of Parts](https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html) specification.

<a id="ckeditor5/latest/features/language.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/language.html--configuring-available-languages">

### Configuring available languages

To modify the list of available languages displayed in the language dropdown use the [config.language.textPartLanguage](../api/module%5Fcore%5Feditor%5Feditorconfig-LanguageConfig.html#member-textPartLanguage) configuration option.

The example below shows the configuration used for the [demo](#ckeditor5/latest/features/language.html--demo) above:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        language: {
            textPartLanguage: [
                { title: 'Arabic', languageCode: 'ar' },
                { title: 'French', languageCode: 'fr' },
                { title: 'Hebrew', languageCode: 'he' },
                { title: 'Spanish', languageCode: 'es' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/language.html--related-features">

### Related features

There are other language-related CKEditor 5 features you may want to check:

* [UI Language](#ckeditor5/latest/getting-started/setup/ui-language.html) – Set the UI language.
* [Spelling and grammar checking](#ckeditor5/latest/features/spelling-and-grammar-checking.html) – Employ multi-language spell check for flawless content.

<a id="ckeditor5/latest/features/language.html--common-api">

### Common API

The [TextPartLanguage](../api/module%5Flanguage%5Ftextpartlanguage-TextPartLanguage.html) plugin registers:

* The `'textPartLanguage'` UI dropdown component implemented by the [text part language UI feature](../api/module%5Flanguage%5Ftextpartlanguageui-TextPartLanguageUI.html).
* The `'textPartLanguage'` command implemented by the [text part language editing feature](../api/module%5Flanguage%5Ftextpartlanguageediting-TextPartLanguageEditing.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Applies the language to the selected text part with the given language code.
editor.execute( 'textPartLanguage', { languageCode: 'es' } );

```

<a id="ckeditor5/latest/features/language.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-language>.

<a id="ckeditor5/latest/features/line-height.html">source file: "ckeditor5/latest/features/line-height.html"</a>

## Line height

The line height feature lets you adjust the vertical spacing between lines of text, controlling how tightly or loosely text is packed within paragraphs. This feature is essential for document formatting, helping users create professional-looking content with proper typography spacing.

<a id="ckeditor5/latest/features/line-height.html--demo">

### Demo

Select content and change the line height using the toolbar button . Please note that the feature can only be applied to whole blocks of content such as paragraphs, tables or lists.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/line-height.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/line-height.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/line-height.html--configuration">

### Configuration

The line height feature provides the following predefined values as options in the dropdown:

* `1`
* `1.15`
* `'default'`
* `2`
* `2.5`
* `3`

While rendering the UI layer, the `'default'` option is replaced with a value determined by the editor’s configuration. By default, the `line-height` value is `1.5`, but you can change this by updating the configuration and content styles. The other values are multipliers of the default one.

* Using a CSS variable in the editor’s content styles:  
```  
:root {
    --ck-content-line-height: 1.65;  
}  
```
* Setting a default value in the editor configuration:  
```  
lineHeight: {  
    defaultValue: 1.65  
}  
```

The [config.lineHeight.defaultValue](../api/module%5Fline-height%5Flineheightconfig-LineHeightConfig.html#member-defaultValue) should be synchronized with the [editor content styles](#ckeditor5/latest/getting-started/setup/css.html).

<a id="ckeditor5/latest/features/line-height.html--using-the-predefined-presets">

#### Using the predefined presets

The line height feature defines 2 named presets:

* `'single'`
* `'double'`

Each size assigns a corresponding class to a block element. For example, the `'double'` preset looks as follows in the editor data:

```
<p class="line-height-double">...</p>

```

The CSS definition for these classes (presets) must be included in the web page styles where the edited content is rendered.

Here is an example of the line height CSS classes:

```
.ck-content .line-height-single {
    line-height: 1;
}

.ck-content .line-height-double {
    line-height: 2;
}

```

An example of an editor that supports more line height sizes:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        lineHeight: {
            options: [
                'single',
                'default',
                'double',
                {
                    title: 'Triple', // A name displayed in the dropdown UI.
                    model: 'triple', // A value used in the command and stored in the model.
                    view: {
                        key: 'class',
                        value: 'line-height-triple'
                    }
                }
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'lineHeight', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

```
.ck-content .line-height-triple {
    line-height: 3;
}

```

<a id="ckeditor5/latest/features/line-height.html--using-numerical-values">

#### Using numerical values

The line height feature also supports numerical values.

In this case, each size adds the `style` attribute to the block element, which sets the `line-height` CSS property. For example, a line height of `2` will be represented in the editor data as:

```
<p style="line-height: 2">...</p>

```

Here is an example of a WYSIWYG editor that supports numerical line heights. Note that `'default'` (`1.5`) is controlled by the default styles of the web page:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        lineHeight: {
            options: [
                0.5,
                1,
                'default', // This will be replaced with the default value (1.5).
                1.65,
                2,
                2.5,
                3
            ]
        },
        toolbar: [
            'heading', 'bulletedList', 'numberedList', 'lineHeight', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/line-height.html--accepting-all-line-height-values">

#### Accepting all line-height values

By default, all `line-height` values that are not specified in the `config.lineHeight.options` are stripped. You can enable support for all line heights by using the [config.lineHeight.supportAllValues](../api/module%5Fline-height%5Flineheightconfig-LineHeightConfig.html#member-supportAllValues) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        lineHeight: {
            options: [
                // Numerical values.
                // ...
            ],
            supportAllValues: true
        },
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/line-height.html--related-features">

### Related features

Check out also these CKEditor 5 features to gain better control over your content style and format:

* [Font styles](#ckeditor5/latest/features/font.html) – Easily and efficiently control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Because it does matter whether the content is left, right, centered, or justified.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Organize your content into visually separated blocks, indent crucial paragraphs, etc.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/line-height.html--common-api">

### Common API

The [LineHeight](../api/module%5Fline-height%5Flineheight-LineHeight.html) plugin registers:

* The `'lineHeight'` dropdown.
* The ['lineHeight'](../api/module%5Fline-height%5Flineheightcommand-LineHeightCommand.html) command.  
The number of options and their names correspond to the [config.lineHeight.options](../api/module%5Fline-height%5Flineheightconfig-LineHeightConfig.html#member-options) configuration option.  
You can change the line height of the current selection by executing the command with a desired value:  
```  
// For numerical values:  
editor.execute( 'lineHeight', { value: 2 } );  
// For named presets:  
editor.execute( 'lineHeight', { value: 'double' } );  
```  
Passing an empty value will remove any `config.lineHeight` set:  
```  
editor.execute( 'lineHeight' );  
```

<a id="ckeditor5/latest/features/link.html">source file: "ckeditor5/latest/features/link.html"</a>

## Link

The link feature lets you insert hyperlinks into your content and provides a UI to create and edit them. Thanks to the [autolink](#ckeditor5/latest/features/link.html--autolink-feature) plugin, typed or pasted URLs and email addresses are automatically converted into working links.

<a id="ckeditor5/latest/features/link.html--demo">

### Demo

Use the link toolbar button  or press Ctrl/Cmd+K to create a new link. Clicking a link opens a contextual toolbar. The toolbar lets you edit existing links  or unlink them  with a click.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/link.html--typing-around-links">

### Typing around links

CKEditor 5 allows typing at the inner and outer link boundaries to make editing simpler for the users.

**To type inside a link**, move the caret to its (start or end) boundary. As long as the link remains highlighted (by default: blue), typing and applying formatting happens within its boundaries:

**To type before or after a link**, move the caret to its boundary, then press the Arrow key (← or →) away from the link once. The link stops from being highlighted, and whatever text you type or formatting apply will not be inside the link:

<a id="ckeditor5/latest/features/link.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/link.html--link-toolbar-configuration">

### Link toolbar configuration

The link UI contains a contextual toolbar that appears when a link is selected. You can configure what items appear in this toolbar using the [config.link.toolbar](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-toolbar) option.

The following toolbar items are available:

* `'linkPreview'` – Shows a preview of the link URL that you can click to open the link in a new tab.
* `'editLink'` – Opens a form to edit the link URL and options.
* `'linkProperties'` – Opens a panel to configure link properties (manual decorators). Only available when at least one manual decorator is defined.
* `'unlink'` – Removes the link.

By default, the link toolbar is configured as follows:

```
ClassicEditor
    .create( {
        link: {
            toolbar: [ 'linkPreview', '|', 'editLink', 'linkProperties', 'unlink' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--custom-toolbar-items">

#### Custom toolbar items

You can extend the link toolbar with custom items by registering them in the [component factory](../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html) and adding them to the toolbar configuration.

Here is an example of registering a custom component:

```
class MyCustomPlugin extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'myCustomLinkInfo', locale => {
            const button = new ButtonView( locale );
            const linkCommand = editor.commands.get( 'link' );

            button.bind( 'isEnabled' ).to( linkCommand, 'value', href => !!href );
            button.bind( 'label' ).to( linkCommand, 'value' );

            button.on( 'execute', () => {
                // Add your custom component logic here
            } );

            return button;
        } );
    }
}

```

Once registered, the component can be used in the toolbar configuration:

```
ClassicEditor
    .create( {
        plugins: [ MyCustomPlugin, /* ... */ ],
        link: {
            toolbar: [ 'myCustomLinkInfo', '|', 'editLink', 'unlink' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--custom-link-attributes-decorators">

### Custom link attributes (decorators)

By default, all links created in the editor have the `href="..."` attribute in the [editor data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--getting-the-editor-data-with-getdata). If you want your links to have additional link attributes, [link decorators](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-decorators) provide an easy way to configure and manage them.

There are two types of link decorators you can use:

* [**Automatic**](#ckeditor5/latest/features/link.html--adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) – They match links against predefined rules and manage their attributes based on the results.
* [**Manual**](#ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators) – They allow users to control link attributes individually using the editor UI.

<a id="ckeditor5/latest/features/link.html--demo-2">

#### Demo

In the editor below, all **external** links get the `target="_blank"` and `rel="noopener noreferrer"` attributes ([automatic decorator](#ckeditor5/latest/features/link.html--adding-attributes-to-links-based-on-predefined-rules-automatic-decorators)). Click a link and edit it  to see that you can control the `download` attribute of specific links using the switch button in the editing balloon ([manual decorator](#ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators)).

The following code runs this editor. Learn more about the [configuration](#ckeditor5/latest/features/link.html--configuration) of the feature.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            // Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
            addTargetToExternalLinks: true,

            // Let the users control the "download" attribute of each link.
            decorators: [
                {
                    mode: 'manual',
                    label: 'Downloadable',
                    attributes: {
                        download: 'download'
                    }
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--configuration">

#### Configuration

You can configure decorators through definitions provided in the [config.link.decorators](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-decorators) configuration option.

Each decorator definition must have a unique name. For [manual decorators](#ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators), the name also represents the decorator in the [document model](#ckeditor5/latest/framework/architecture/editing-engine.html--text-attributes).

<a id="ckeditor5/latest/features/link.html--adding-target-and-rel-attributes-to-external-links">

##### Adding `target` and `rel` attributes to external links

A common use case for (automatic) link decorators is adding the `target="_blank"` and `rel="noopener noreferrer"` attributes to all external links in the document. A dedicated [config.link.addTargetToExternalLinks](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-addTargetToExternalLinks) configuration exists for that purpose. When you set this option to `true`, all links starting with `http://`, `https://`, or `//` are “decorated” with `target` and `rel` attributes.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            addTargetToExternalLinks: true
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Internally, this configuration corresponds to an [automatic decorator](#ckeditor5/latest/features/link.html--adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) with the following [definition](../api/module%5Flink%5Flinkconfig-LinkDecoratorAutomaticDefinition.html):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            decorators: {
                addTargetToExternalLinks: {
                    mode: 'automatic',
                    callback: url => /^(https?:)?\/\//.test( url ),
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

If you want to leave the decision whether a link should open in a new tab to the users, do not use the `config.link.addTargetToExternalLinks` configuration. Define a new [manual decorator](#ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators) with the following definition instead:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            decorators: {
                openInNewTab: {
                    mode: 'manual',
                    label: 'Open in a new tab',
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--adding-default-link-protocol-to-external-links">

##### Adding default link protocol to external links

A default link protocol can be useful when the user forgets to type the full URL address to an external source or website. Sometimes copying the text, like for example `ckeditor.com`, and converting it to a link may cause some issues. As a result, the created link will direct you to `yourdomain.com/ckeditor.com` because of the missing protocol. This makes the link relative to the site where it appears.

After you enable the [config.link.defaultProtocol](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-defaultProtocol) configuration option, the link feature will be able to handle this issue for you. By default, it does not fix the passed link value, but when you set [config.link.defaultProtocol](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-defaultProtocol) to, for example, `http://`, the plugin will add the given protocol to every link that may need it (like `ckeditor.com`, `example.com`, etc. where `[protocol://]example.com` is missing).

See a basic configuration example:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            defaultProtocol: 'http://'
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--adding-custom-protocols-in-links">

##### Adding custom protocols in links

By default, a minimal set of protocols is allowed to be used in the links. Any URL with an unrecognized protocol will be changed to ‘#’. You can overwrite the list of protocols by using [config.link.allowedProtocols](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-allowedProtocols).

See a configuration example:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            // You can use `s?` suffix like below to allow both `http` and `https` protocols at the same time.
            allowedProtocols: [ 'https?', 'tel', 'sms', 'sftp', 'smb', 'slack' ]
        }
        // More of the editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--adding-attributes-to-links-based-on-predefined-rules-automatic-decorators">

##### Adding attributes to links based on predefined rules (automatic decorators)

Automatic link decorators match all links in the editor content against a [function](../api/module%5Flink%5Flinkconfig-LinkDecoratorAutomaticDefinition.html) which decides whether the link should receive some set of attributes, considering the URL (`href`) of the link. These decorators work silently and the editor applies them during the [data downcast](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion).

For instance, to create an automatic decorator that adds the `download="file.pdf"` attribute to all links ending with the `".pdf"` extension, you should add the following [definition](../api/module%5Flink%5Flinkconfig-LinkDecoratorAutomaticDefinition.html) to [config.link.decorators](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-decorators):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            decorators: {
                detectDownloadable: {
                    mode: 'automatic',
                    callback: url => url.endsWith( '.pdf' ),
                    attributes: {
                        download: 'file.pdf'
                    }
                }
            }
        }
        // More of the editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--adding-classes-and-styles-to-links">

##### Adding classes and styles to links

In addition to adding custom HTML attributes, link decorators can also apply CSS classes and inline styles to a link. It works for both **automatic** decorators (based on rules) and **manual** decorators (toggled in the UI). You must provide classes and styles through the dedicated `classes` and `styles` properties in the decorator configuration.

Manual decorators add a toggle to the link UI, allowing the user to enable or disable additional link features. The decorator properties are applied to the link element whenever the toggle is enabled.

```
ClassicEditor
    .create( {
        link: {
            decorators: {
                highlighted: {
                    mode: 'manual',
                    label: 'Highlighted link',
                    defaultValue: false,
                    classes: 'link-highlighted',
                    styles: {
                        background: 'yellow',
                        'font-weight': 'bold'
                    }
                }
            }
        }
    } );

```

When you enable the “Highlighted link” toggle, the editor output adds the class and styles to the link element.

<a id="ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators">

##### Adding attributes to links using the UI (manual decorators)

Manual link decorators are represented in the link editing balloon as switch buttons. The users can use them to control the presence of attributes of a particular link (check out the [demo](#ckeditor5/latest/features/link.html--demo) to learn more). Each manual decorator [definition](../api/module%5Flink%5Flinkconfig-LinkDecoratorManualDefinition.html) has a human-readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.

To configure a “Downloadable” switch button in the link editing balloon that adds the `download="file"` attribute to the link when turned on, add the following definition to [config.link.decorators](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-decorators):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        link: {
            decorators: {
                toggleDownloadable: {
                    mode: 'manual',
                    label: 'Downloadable',
                    attributes: {
                        download: 'file'
                    }
                },
                openInNewTab: {
                    mode: 'manual',
                    label: 'Open in a new tab',
                    defaultValue: true,			// This option will be selected by default.
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/link.html--deprecated-syntax">

##### Deprecated syntax

Older versions of CKEditor 5 allowed classes and styles inside the `attributes` field:

```
// ❌ Deprecated – do not use:
attributes: {
    class: 'my-class',
    style: 'color: red'
}

```

<a id="ckeditor5/latest/features/link.html--autolink-feature">

### Autolink feature

The [AutoLink](../api/module%5Flink%5Fautolink-AutoLink.html) feature will automatically turn URLs or email addresses into working links.

To use the autolink function, press Space, Enter, or Shift+Enter after a link.

<a id="ckeditor5/latest/features/link.html--link-providers">

### Link providers

<a id="ckeditor5/latest/features/link.html--demo-3">

#### Demo

The link feature integrates with [bookmarks](#ckeditor5/latest/features/bookmarks.html), providing a smooth linking experience. Link providers allow adding predefined lists of links (similar to bookmarks). You can register any links you would like to use frequently in your content in the Link plugin using a custom method. These links will be available in the link UI form for easy access.

<a id="ckeditor5/latest/features/link.html--configuration-2">

#### Configuration

To define a list of links available in the link UI, you can use the `getListItems()` function in the link provider. Opening the group in the link UI calls the function every time. The function should return an array of objects, each representing a link.

The `getItem()` function can resolve the link. Opening the link preview or navigating to the link from the editing view calls the function. It should return an object with the `href`, `icon`, `label`, and `tooltip` parameters. The properties are assigned to the link preview. It is useful when only part of the list items are shown in the list view (for example, in pagination), and the user interacts with a link that is not visible in the list view but is available in the editing.

```
class SocialLinksPlugin extends Plugin {
    static get requires() {
        return [ Link ];
    }

    async init() {
        const linkUI = this.editor.plugins.get( LinkUI );

        linkUI.registerLinksListProvider( {
            label: 'Social links',
            getListItems: () => [
                {
                    id: 'facebook',
                    href: 'https://facebook.com',
                    label: 'Facebook',
                    icon: linkIcon
                },
                {
                    id: 'twitter',
                    href: 'https://twitter.com',
                    label: 'Twitter',
                    icon: linkIcon
                }
            ],

            // Optionally: You can customize your link preview by custom implementation of link getter.
            getItem: href => {
                return {
                    href,
                    icon: linkIcon,
                    label: 'My custom label in link preview',
                    tooltip: 'My custom tooltip in link preview'
                };
            }
        } );
    }
}

```

<a id="ckeditor5/latest/features/link.html--common-api">

### Common API

The [Link](../api/module%5Flink%5Flink-Link.html) plugin registers the UI button component (`'link'`) and the following commands:

* The `'link'` command implemented by [LinkCommand](../api/module%5Flink%5Flinkcommand-LinkCommand.html).
* The `'unlink'` command implemented by [UnlinkCommand](../api/module%5Flink%5Funlinkcommand-UnlinkCommand.html).

You can execute the commands using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Applies the link to the selected content.
// When the selection is collapsed, it creates new text wrapped in a link.
editor.execute( 'link', 'http://example.com' );

// If there are decorators configured, the command can set their state.
editor.execute( 'link', 'http://example.com', { linkIsExternal: true } );

// Removes the link from the selection (and all decorators if present).
editor.execute( 'unlink' );

```

The package provides a plugin for [linking images](../api/module%5Flink%5Flinkimage-LinkImage.html). See the [Linking images](#ckeditor5/latest/features/images/images-linking.html) guide in the [Images section](#ckeditor5/latest/features/images/images-overview.html).

Links are represented in the [model](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html) using the `linkHref` attribute. [Manual link decorators](#ckeditor5/latest/features/link.html--adding-attributes-to-links-using-the-ui-manual-decorators) are represented in the model using text attributes corresponding to their names, as configured in [config.link.decorators](../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-decorators).

<a id="ckeditor5/latest/features/link.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-link>.

<a id="ckeditor5/latest/features/lists/lists-editing.html">source file: "ckeditor5/latest/features/lists/lists-editing.html"</a>

## Lists editing behavior

This article describes the functionality and behaviors of lists in CKEditor 5.

<a id="ckeditor5/latest/features/lists/lists-editing.html--block-lists">

### Block lists

Since version 41.0.0, the list feature allows any part of the content to be part of a list. You can put content blocks and elements – such as images, tables, paragraphs, headings, and others – inside a list item, ensuring the continuity of numbering and retaining indentation.

To edit a block inside a list item, press Enter to create a new line and then Backspace to remove the new list item marker. Keep on entering content. Observe this behavior in the screencast below.

<a id="ckeditor5/latest/features/lists/lists-editing.html--managing-lists-with-keyboard">

### Managing lists with keyboard

Press Enter to create a new list item. Press Tab to nest the item (in multi-level lists) or indent it (in regular lists). Press Enter to turn an item into a higher level in the list or to remove it completely.

<a id="ckeditor5/latest/features/lists/lists-editing.html--simple-lists">

### Simple lists

When working with simple content or in small editing areas, you might not need the support for multi-block lists. You can use the [config.list.multiBlock](../../api/module%5Flist%5Flistconfig-ListConfig.html#member-multiBlock) configuration setting to turn off the block list functionality. When you set this option to `false`, users can only insert text into list items. They will not be able to nest content blocks – like paragraphs or tables – inside a list item. We sometimes refer to this setup as “simple lists.”

<a id="ckeditor5/latest/features/lists/lists-editing.html--merging-adjacent-lists">

### Merging adjacent lists

By default, the editor merges two ordered and unordered lists of the same type that are next to each other. This happens to preserve the user intention. Lists that visually appear to be one continuous list should constitute one list even if the user has accidentally created several of them.

Sometimes this can be an undesirable behavior. For example, two adjacent numbered lists, each with two items, will merge into a single list with the numbers 1 through 4.

To prevent this behavior, enable the [AdjacentListsSupport](../../api/module%5Flist%5Flist%5Fadjacentlistssupport-AdjacentListsSupport.html) plugin.

This feature only works for pasted contents or on data load, it does not support entering adjacent lists via the editor UI. Find more about it in the `#changes-to-list-merging` section of `Update to 41.x` guide in the [updating from older versions](#ckeditor5/latest/updating/guides/updating-from-older-versions.html) guide. If you are interested in this functionality, refer to [this issue on GitHub](https://github.com/ckeditor/ckeditor5/issues/14478).

<a id="ckeditor5/latest/features/lists/lists-editing.html--indenting-lists">

### Indenting lists

Besides controlling [text block indentation](#ckeditor5/latest/features/indent.html), the indent  and outdent  buttons allow for indenting list items (nesting them).

This mechanism is transparent to the user. From the code perspective, the buttons are implemented by the [Indent](../../api/module%5Findent%5Findent-Indent.html) plugin. Neither these buttons nor the respective commands implement any functionality by default.

The target behavior comes from two other plugins:

* [IndentBlock](../../api/module%5Findent%5Findentblock-IndentBlock.html) – The indent block feature controls the indentation of elements such as paragraphs and headings.
* [List](../../api/module%5Flist%5Flist-List.html) – The list feature implements the indentation (nesting) of lists.

This means that if you want to allow indenting lists only, you can do that by loading just the `Indent` and `List` plugins.

When both the `IndentBlock` and `List` plugins are loaded, the editor also supports visual block indentation of list containers (`<ol>`, `<ul>`) and list items (`<li>`), applying a `margin-left` style or CSS class. Refer to the [Indenting lists](#ckeditor5/latest/features/indent.html--indenting-lists) section in the block indentation guide for details on the behavior, UX, and configuration.

If you want the full behavior – nesting list items, block indentation of paragraphs, and visual block indentation of lists – you need to load all three plugins: `Indent`, `IndentBlock`, and `List`.

<a id="ckeditor5/latest/features/lists/lists-properties.html">source file: "ckeditor5/latest/features/lists/lists-properties.html"</a>

## List properties

Besides the basic functionality of creating ordered and unordered lists, CKEditor 5 offers formatting tools that let you control the lists. You can enable features such as customizing list markers with additional styles, setting the start index, or reversing the list order separately or all at once. Check out the individual demos below or see all list properties working together in the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html).

<a id="ckeditor5/latest/features/lists/lists-properties.html--list-styles">

### List styles

The list style feature introduces more styles for the list item markers. When [enabled](../../api/module%5Flist%5Flistconfig-ListPropertiesConfig.html#member-styles), it adds three styles for unordered lists and six styles for ordered lists to choose from. The user will be able to set or change the list style via the dropdown. It opens when you click the arrow next to the appropriate list button in the toolbar.

<a id="ckeditor5/latest/features/lists/lists-properties.html--available-list-styles">

#### Available list styles

The following unordered list styles are available:

* `disk` (•)
* `circle` (◦)
* `square` (▪)

The following ordered list styles are available:

* `decimal` (1.)
* `decimal-leading-zero` (01.)
* `lower-roman` (i.)
* `upper-roman` (I.)
* `lower-latin` (a.)
* `upper-latin` (A.)

Additional numbering style that [needs configuration](#ckeditor5/latest/features/lists/lists.html--enabling-specific-enumerators):

* arabic-indic numbers (١.)

<a id="ckeditor5/latest/features/lists/lists-properties.html--demo">

#### Demo

In the editor below, use the ordered  or unordered list dropdown  to choose the desired marker type for each list.

<a id="ckeditor5/latest/features/lists/lists-properties.html--list-start-index">

### List start index

The list start index feature allows the user to choose the starting point of an ordered list. By default, this would be `1` (or `A`, or `I` – see the [list styles section](#ckeditor5/latest/features/lists/lists-properties.html--list-styles)). Sometimes you may want to start a list with some other digit or letter, though.

When this feature is [enabled](../../api/module%5Flist%5Flistconfig-ListPropertiesConfig.html#member-startIndex), an extra dropdown option is available in the ordered list toolbar button. Thanks to it, the user may set or change the starting marker.

<a id="ckeditor5/latest/features/lists/lists-properties.html--demo-2">

#### Demo

In the editor below, notice how the ordering continues in the second list. To achieve continuous numbering of all spaceships from the example, go to the first item of the last list. Then use the ordered list  dropdown input field to set the start index.

<a id="ckeditor5/latest/features/lists/lists-properties.html--reversed-list">

### Reversed list

The reversed list feature lets the user reverse the numbering order of a list, changing it from ascending to descending. This is useful in countdowns and things-to-do lists that need to reproduce steps in a reversed order (for example, in disassembly instructions).

When this feature is [enabled](../../api/module%5Flist%5Flistconfig-ListPropertiesConfig.html#member-reversed), an extra dropdown switch is available in the ordered list toolbar button. Thanks to it, the user may reverse the order of a list with a single click.

<a id="ckeditor5/latest/features/lists/lists-properties.html--demo-3">

#### Demo

Click the second list and use the ordered list  dropdown switch to choose whether to reverse the numbering order.

<a id="ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting">

### List item marker formatting

The list item marker formatting feature automatically applies text formatting to list item markers when the entire content of the list item shares the same formatting. It integrates with the [font feature](#ckeditor5/latest/features/font.html) and [basic styles feature](#ckeditor5/latest/features/basic-styles.html), supporting the following formatting options:

* **Bold** and **italic** (from basic styles),
* **Font color**, **font size**, and **font family** (from font).

When this feature is enabled, if the whole list item content is consistently styled using any of the supported formats, the bullet or number marker will reflect the same style automatically. For example, if a list item is entirely bold, its marker will appear bold as well.

<a id="ckeditor5/latest/features/lists/lists-properties.html--demo-4">

#### Demo

Select the entire content of a list item and apply a format like bold, italic, or a font style. If the whole item is formatted, the list marker will automatically update to match.

<a id="ckeditor5/latest/features/lists/lists-properties.html--disabling-marker-formatting">

#### Disabling marker formatting

This feature is enabled by default. To disable it, use the following configuration:

<a id="ckeditor5/latest/features/lists/lists.html">source file: "ckeditor5/latest/features/lists/lists.html"</a>

## Ordered and unordered lists

The list feature lets you create ordered (numbered) and unordered (bulleted) lists. The unique thing about them is that you can put any content inside each list item (including block elements like paragraphs and tables), retaining the continuity of numbering and indentation.

<a id="ckeditor5/latest/features/lists/lists.html--demo">

### Demo

Use the editor below to see the list feature in action. You can use toolbar buttons to insert both ordered  and unordered lists .

You can also use Markdown code recognized by the [autoformatting feature](#ckeditor5/latest/features/autoformat.html):

* Start a line with `*` or `-` followed by a space for a bulleted list.
* Start a line with `1.` or `1)` followed by a space for a numbered list.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/lists/lists.html--installation">

### Installation

The `List` plugin provides the [ordered (numbered) and unordered (bulleted) features](#ckeditor5/latest/features/lists/lists.html) for CKEditor 5\. [Additional list properties](#ckeditor5/latest/features/lists/lists-properties.html), such as list marker styles, start index, or reversed list order, are provided by the `ListProperties` plugin.

<a id="ckeditor5/latest/features/lists/lists.html--list-feature">

#### List feature

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/lists/lists.html--list-properties">

#### List properties

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add `ListProperties` to your plugin list and toolbar configuration:

To enable selected sub-features of the [list properties](#ckeditor5/latest/features/lists/lists-properties.html), add their configuration to your editor. Set `true` for each feature you want to enable:

<a id="ckeditor5/latest/features/lists/lists.html--enabling-specific-enumerators">

##### Enabling specific enumerators

To enable only selected list item enumerators for the ordered list, you need to explicitly list them in the editor configuration. This can also be used to enable additional, `arabic-indic` numeral enumerators. To achieve this, replace the `styles: true` configuration option with a `styles { }` listing, for example:

```
list: {
    properties: {
        styles: {
            listStyleTypes: {
                numbered: [
                    'decimal',
                    'decimal-leading-zero',
                    'arabic-indic'
                ],
                bulleted: [
                    'disc',
                    'circle',
                    'square'
                ]
            }
        }
    }
}

```

<a id="ckeditor5/latest/features/lists/lists.html--editor-output-configuration">

#### Editor output configuration

Starting with version 45.1.1, list items (`<li>` elements) in the editor data output contain an additional attribute `data-list-item-id`. The attribute is necessary to ensure that the lists feature work correctly with other editor features and mechanisms.

```
<ul>
    <li data-list-item-id="e72808ee4144975064acb5d66e5cfba13">Hello</li>
    <li data-list-item-id="e5d719ab356409767e9d4358485476358">There!</li>
</ul>

```

If data loaded in the editor does not contain the `data-list-item-id` attributes on list items, they will be automatically added when data is saved.

If you wish to save the editor contents without this attribute, you can set the `skipListItemIds` flag to `true` when calling `editor.getData()` method. **However, please note, that data without IDs should be used only for presentation purposes (such as displaying the document as HTML), and should not be used to initialize the editor.**

```
editor.getData( { skipListItemIds: true } );

```

Such output will not contain `data-list-item-id` attribute:

```
<ul>
    <li>Hello</li>
    <li>There!</li>
</ul>

```

<a id="ckeditor5/latest/features/lists/lists.html--related-features">

### Related features

These CKEditor 5 features provide similar functionality:

* [To-do lists](#ckeditor5/latest/features/lists/todo-lists.html) – Create a list of interactive checkboxes with labels.
* [Multi-level lists](#ckeditor5/latest/features/lists/multi-level-lists.html) – Multi-level lists allow the user to set different markers (symbols, text or numbers) to display at each level of the list.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Set indentation for text blocks such as paragraphs or headings. Also supports [visual block indentation of lists and list items](#ckeditor5/latest/features/indent.html--indenting-lists).
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the text on the go with Markdown code.

<a id="ckeditor5/latest/features/lists/lists.html--common-api">

### Common API

The [List](../../api/module%5Flist%5Flist-List.html) plugin registers:

* The ['numberedList'](../../api/module%5Flist%5Flist%5Flistcommand-ListCommand.html) command.
* The ['bulletedList'](../../api/module%5Flist%5Flist%5Flistcommand-ListCommand.html) command.
* The ['indentList'](../../api/module%5Flist%5Flist%5Flistindentcommand-ListIndentCommand.html) command.
* The ['outdentList'](../../api/module%5Flist%5Flist%5Flistindentcommand-ListIndentCommand.html) command.
* The `'numberedList'` UI button.
* The `'bulletedList'` UI button.

The [ListProperties](../../api/module%5Flist%5Flistproperties-ListProperties.html) plugin registers:

* The [listStyle](../../api/module%5Flist%5Flistproperties%5Fliststylecommand-ListStyleCommand.html) command. It accepts the `type` of the list style to set. If not set, it uses the default marker (usually decimal).  
```  
editor.execute( 'listStyle', { type: 'lower-roman' } );  
```  
The available types are:

  * For bulleted lists: `'disc'`, `'circle'`, and `'square'`.
  * For numbered lists: `'decimal'`, `'decimal-leading-zero'`, `'lower-roman'`, `'upper-roman'`, `'lower-latin'`, and `'upper-latin'`.
* The [listStart](../../api/module%5Flist%5Flistproperties%5Fliststartcommand-ListStartCommand.html) command. It is a number and defaults to `1` (meaning a list starts with `1`). If enabled, it accepts a numerical value for the `start` attribute.  
```  
editor.execute( 'listStart', { startIndex: 3 } );  
```
* The [listReversed](../../api/module%5Flist%5Flistproperties%5Flistreversedcommand-ListReversedCommand.html) command. It is a Boolean and defaults to `false` (meaning the list order is ascending).  
```  
editor.execute( 'listReversed', { reversed: true } );  
```
* The `numberedList` UI split button. It overrides the UI button registered by the `List` plugin.
* The `bulletedList` UI split button. It overrides the UI button registered by the `List` plugin.

<a id="ckeditor5/latest/features/lists/lists.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list>.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html">source file: "ckeditor5/latest/features/lists/multi-level-lists.html"</a>

## Multi-level lists

Multi-level lists with the legal style numbering feature allows for easy creation and modification of numbered lists with counters (1, 1.1, 1.1.1). These are crucial for clear referencing and hierarchical organization in complex documents. The feature offers full compatibility with Microsoft Word. When lists with such formatting are pasted to the editor with the [paste from Office enhanced](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) feature, the numbering format is retained.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--demo">

### Demo

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--additional-feature-information">

### Additional feature information

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--headings-in-multi-level-lists">

#### Headings in multi-level lists

Multi-level lists support headings in list items. The marker, which denotes the counter, will insert itself into the heading block to achieve more similar styles.

While creation of a legal document with a list of numbered headings is possible, the editing of long-form documents may not be the best experience. You might want full support for the **numbered headings feature** that Microsoft Word places in the multi-level lists interface. We do not have it yet, but if you are interested, please let us know in [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/16161) or via our support.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--custom-multi-level-list-styles">

#### Custom multi-level list styles

For now, we provide one style for multi-level lists: legal style numbering. But this first step opens a possibility for us to add more styles in the future or allow integrators to create their own styles. If you are interested, please let us know in [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/8687) or via our support.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the features to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--related-features">

### Related features

* [Ordered and unordered lists](#ckeditor5/latest/features/lists/lists.html) – Create ordered and unordered lists with configurable markers.
* [To-do lists](#ckeditor5/latest/features/lists/todo-lists.html) – Create a list of interactive checkboxes with labels.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Set indentation for text blocks such as paragraphs or headings and lists.
* [Paste from Office enhanced](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) – Paste Office documents with high compatibility.

<a id="ckeditor5/latest/features/lists/multi-level-lists.html--common-api">

### Common API

The [MultiLevelList](../../api/module%5Flist-multi-level%5Fmultilevellist-MultiLevelList.html) registers:

* The `'multiLevelList'` UI dropdown component.
* The `'multiLevelList'` command implemented by [MultiLevelListCommand](../../api/module%5Flist-multi-level%5Fmultilevellistcommand-MultiLevelListCommand.html).

You can execute the command using the [editor.execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Change selected content to multi level list.
editor.execute( 'multiLevelList' );

```

<a id="ckeditor5/latest/features/lists/todo-lists.html">source file: "ckeditor5/latest/features/lists/todo-lists.html"</a>

## To-do lists

The to-do list feature lets you create a list of interactive checkboxes with labels. It supports all features of [bulleted and numbered lists](#ckeditor5/latest/features/lists/lists.html), so you can nest a to-do list together with any combination of other lists.

<a id="ckeditor5/latest/features/lists/todo-lists.html--demo">

### Demo

Use the to-do list toolbar button  to add a list to the editor content. Thanks to the integration with the [autoformatting feature](#ckeditor5/latest/features/autoformat.html), you can also start a line with `[ ]` or `[x]` followed by a space to insert an unchecked or checked list item.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/lists/todo-lists.html--keyboard-support">

### Keyboard support

You can check and clear a list item by using the Ctrl \+ Enter (Cmd \+ Enter on Mac) shortcut when the selection is in that item.

<a id="ckeditor5/latest/features/lists/todo-lists.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/lists/todo-lists.html--related-features">

### Related features

These CKEditor 5 features provide similar functionality:

* [Ordered and unordered lists](#ckeditor5/latest/features/lists/lists.html) – Create ordered and unordered lists with configurable markers.
* [Multi-level lists](#ckeditor5/latest/features/lists/multi-level-lists.html) – Multi-level lists allow the user to set different markers (symbols, text or numbers) to display at each level of the list.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format the text on the go with Markdown code.

<a id="ckeditor5/latest/features/lists/todo-lists.html--common-api">

### Common API

The [TodoList](../../api/module%5Flist%5Ftodolist-TodoList.html) plugin registers:

* The ['todoList'](../../api/module%5Flist%5Flist%5Flistcommand-ListCommand.html) command.
* The ['checkTodoList'](../../api/module%5Flist%5Ftodolist%5Fchecktodolistcommand-CheckTodoListCommand.html) command.
* The `'todoList'` UI button.

<a id="ckeditor5/latest/features/lists/todo-lists.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list>.

<a id="ckeditor5/latest/features/markdown.html">source file: "ckeditor5/latest/features/markdown.html"</a>

## Markdown output

The Markdown plugin lets you switch the default output from HTML to Markdown. This way you can produce lightweight text documents with a simple formatting syntax that is popular among developers.

<a id="ckeditor5/latest/features/markdown.html--demo">

### Demo

The editor below is configured to output GitHub Flavored Markdown. Edit the content and see how the Markdown output changes (you can find it below the editor).

Output:

<a id="ckeditor5/latest/features/markdown.html--snippet-markdown-output">

```

```

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/markdown.html--additional-feature-information">

### Additional feature information

Coupled with the [autoformatting](#ckeditor5/latest/features/autoformat.html) feature, the Markdown plugin offers the full-fledged Markdown WYSIWYG editing experience, as described in the [“CKEditor 5: the best open source Markdown editor”](https://ckeditor.com/blog/CKEditor-5-the-best-open-source-Markdown-editor/) blog post. Visit the [free online Markdown editor](https://onlinemarkdowneditor.dev/) to see this solution implemented.

Please remember that Markdown syntax is really simple and it does not cover all the rich-text features. Some features provided by CKEditor 5 will thus work as intended only when output to HTML as they have no Markdown equivalent.

<a id="ckeditor5/latest/features/markdown.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the [Markdown](../api/module%5Fmarkdown-gfm%5Fmarkdown-Markdown.html) plugin to the editor configuration. It will change the default [data processor](../api/module%5Fengine%5Fdataprocessor%5Fdataprocessor-DataProcessor.html) to the [MarkdownGfmDataProcessor](../api/module%5Fmarkdown-gfm%5Fgfmdataprocessor-MarkdownGfmDataProcessor.html):

<a id="ckeditor5/latest/features/markdown.html--extending-formatting-support">

### Extending formatting support

If you need more extensive Markdown support for formatting elements (for example, having the `title` attribute on links represented as `[Foo Bar](https://foo.bar "My link title")`), you can also install [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html). This advanced feature allows the integrators to provide additional tags, elements, and attributes, not yet supported by other CKEditor 5 plugins and extend the formatting capabilities.

<a id="ckeditor5/latest/features/markdown.html--the-markdown-data-processor">

### The Markdown data processor

The Markdown plugin uses a [data processor](../api/module%5Fengine%5Fdataprocessor%5Fdataprocessor-DataProcessor.html) (implemented by the [MarkdownGfmDataProcessor](../api/module%5Fmarkdown-gfm%5Fgfmdataprocessor-MarkdownGfmDataProcessor.html) class) which changes the default output from HTML to Markdown. This means that you can [set](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData) or [get](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) data from the editor in the Markdown format:

```
editor.getData(); // -> 'This is [CKEditor&nbsp;5](https://ckeditor.com).'

editor.setData( 'This is **bold**.' );

```

The data processor outputs the GFM Markdown syntax. “GFM” stands for “GitHub Flavored Markdown” – a Markdown dialect used by [GitHub](https://github.com). Markdown lacks any formal specification (although the [CommonMark](https://commonmark.org/) initiative aims to close this gap) and has many dialects, often incompatible with one another.

When converting the output produced by this data processor, make sure to use a compatible Markdown-to-HTML converter (for example, the [marked](https://www.npmjs.com/package/marked) library).

<a id="ckeditor5/latest/features/markdown.html--known-issues">

### Known issues

While the Markdown plugin is stable and ready to use, some issues are still being worked on. Feel free to upvote 👍 these on GitHub if you would like to see this introduced.

* Pasting Markdown-formatted content does not automatically convert the pasted syntax markers into properly formatted content. GitHub issues: [#2321](https://github.com/ckeditor/ckeditor5/issues/2321), [#2322](https://github.com/ckeditor/ckeditor5/issues/2322).
* The Markdown code generated with the Markdown output feature will not properly render [nested tables](#ckeditor5/latest/features/tables/tables.html--nesting-tables). GitHub issue: [#9475](https://github.com/ckeditor/ckeditor5/issues/9475).
* Code blocks inside To-do lists will not properly render. GitHub issue: [#18754](https://github.com/ckeditor/ckeditor5/issues/18754).

<a id="ckeditor5/latest/features/markdown.html--related-features">

### Related features

Some other ways to output the edited content include:

* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html--markdown-source-view) – Allows for Markdown source edition if configured accordingly.
* [Export to Word](#ckeditor5/latest/features/converters/export-word.html) – Generate editable `.docx` files out of your editor-created content.
* [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) – Generate portable PDF files out of your editor-created content.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Use Markdown syntax shortcodes to automatically format your content as you type!
* [Paste Markdown](#ckeditor5/latest/features/pasting/paste-markdown.html) – Paste Markdown-formatted content straight into the editor.

<a id="ckeditor5/latest/features/markdown.html--contribute">

### Contribute

The source code of this feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-markdown-gfm>.

<a id="ckeditor5/latest/features/math-equations.html">source file: "ckeditor5/latest/features/math-equations.html"</a>

## Math equations and chemical formulas

[MathType](http://www.wiris.com/en/mathtype) is a popular mathematical and science formula editor with classical and handwriting input modes. You can use it to create math equations or chemical formulas right inside the CKEditor 5 content.

<a id="ckeditor5/latest/features/math-equations.html--demo">

### Demo

To create math or chemical formulas in the editor below, click the MathType  or ChemType  buttons in the toolbar. This will open the relevant dialog.

Use the toolbar to write your equation or formula. At any time, you can also click the “Go to handwritten mode” button on the right side of the MathType editor to switch to handwriting.

When you are done creating your scientific content, click the “OK” button to insert your formula into the editor. You can also edit any existing formulas by double-clicking them in your document.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/math-equations.html--additional-feature-information">

### Additional feature information

MathType is based upon standards like MathML for internal representation and the PNG image format for displaying formulas. It can also handle other formats like LaTeX, Flash, SVG, and EPS.

Additionally, MathType offers a special tool designed to help you work with chemical notation. When enabled, ChemType adds a specialized toolbar with the common chemical symbols as well as changes the notation to make it more intuitive to work with chemical formulas.

<a id="ckeditor5/latest/features/math-equations.html--usage">

### Usage

The MathType window is split into two main areas: a [tabbed toolbar](https://docs.wiris.com/mathtype/en/user-interfaces/mathtype-web-interface/toolbar-and-icons.html) that contains a large number of icons that are useful for creating math equations and chemical formulas, and an editing area where you can see your current formula, the location of the cursor, and the text currently selected (if any).

The following resources can come in handy if you want to become proficient at working with this tool:

* [Using MathType Web](https://docs.wiris.com/mathtype/en/user-interfaces/mathtype-web-interface/using-mathtype.html) covers the basics of creating formulas, using your keyboard, moving the cursor in templates, formatting your content, or writing on mobile devices.
* [Introductory tutorials](https://docs.wiris.com/mathtype/en/user-interfaces/mathtype-web-interface/introductory-tutorials.html) are intended to get you started using MathType.
* [ChemType](https://docs.wiris.com/mathtype/en/mathtype-integrations/mathtype-web-interface-features/chemistry.html) explains the features of the dedicated chemistry toolbar.
* [MathType documentation](https://docs.wiris.com/mathtype/index.html) is a complete reference to all MathType features and settings.

<a id="ckeditor5/latest/features/math-equations.html--editing-modes">

### Editing modes

MathType lets you choose between two editing modes:

* **Classic input mode** provides options to choose symbols and templates from the MathType or ChemType toolbars and combine them to build the equation.
* **Handwritten input mode** lets you write the equation in your own handwriting. After checking the equation preview to ensure its accuracy, you can insert the equation or switch to classic input for further editing. [Read more here](https://docs.wiris.com/mathtype/en/mathtype-integrations/mathtype-web-interface-features/handwritten-input.html).

If you visit a page using MathType with your mobile device, the handwriting interface will appear by default. However, if you visit the same page with a laptop or desktop computer, the classic input will be displayed. The user is always free to change between the two interfaces.

<a id="ckeditor5/latest/features/math-equations.html--installation-from-npm">

### Installation from npm

MathType is delivered as a CKEditor 5 plugin, so it can be combined into an editor preset just like other features. To add this feature to your editor, install the [@wiris/mathtype-ckeditor5](https://www.npmjs.com/package/@wiris/mathtype-ckeditor5) package:

```
npm install --save @wiris/mathtype-ckeditor5

```

Then add it to your plugin list and the toolbar configuration. Please note, that unlike native CKEditor 5 plugins, this one is imported from its own package. Also, that this import is different than the standard CKEditor 5 plugins import:

```
import { ClassicEditor } from 'ckeditor5';
import MathType from '@wiris/mathtype-ckeditor5/dist/index.js';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ MathType, /* ... */ ],
        toolbar: [ 'MathType', 'ChemType', /* ... */ ],
        mathTypeParameters : {
            // Configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/math-equations.html--installation-from-cdn">

### Installation from CDN

The MathType plugin is provided by an external partner. Hence, after attaching the editor scripts, you cannot access the plugin from the global variable as with other plugins. However, there is a way to use the CKEditor 5 CDN with the MathType plugin. It requires a custom setup.

First, copy the MathType files from the [@wiris/mathtype-ckeditor5/dist/browser](https://www.npmjs.com/package/@wiris/mathtype-ckeditor5?activeTab=code) package to your project. It may look like this:

```
├── mathtype
│    ├── index-content.css
│    ├── index-editor.css
│    ├── index.css
│    ├── index.css.map
│    ├── index.js
│    ├── index.js.map
│    ├── index.umd.js
│    └── index.umd.js.map
├── ...

```

Next, attach the MathType script to your page after the editor scripts. This will expose MathType as a global variable, similar to other plugins.

```
<script src="./mathtype/index.umd.js"></script>

```

Besides the script, you also need to attach the CSS file.

```
<link rel="stylesheet" href="./mathtype/index.css" />

```

Once the scripts are added, get MathType from the UMD file loaded via the script tag. Use the MathType plugin directly from exports, then add it to the editor.

```
const { ClassicEditor } = window.CKEDITOR;

const MathTypeExports = window['@wiris/mathtype-ckeditor5'];
const MathType = MathTypeExports.default;

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ MathType, /* ... */ ],
        toolbar: [ 'MathType', 'ChemType', /* ... */ ],
        mathTypeParameters : {
            // Configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/math-equations.html--customizing-mathtype-service">

### Customizing MathType service

It is possible to use different services for MathType support. There are several ways to deploy it in the CKEditor 5 environment. The following instructions will allow you to customize MathType Web Integration services for CKEditor 5.

<a id="ckeditor5/latest/features/math-equations.html--java">

#### Java

To install the Java service, follow the steps below:

1. Download the [MathType Web Integration Services - Java](https://store.wiris.com/en/products/downloads/mathtype/integrations) package.
2. Deploy the `pluginwiris_engine` war file.
3. Add `mathTypeParameters` to CKEditor 5 with the configuration shown below:  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        // MathType parameters.  
        mathTypeParameters : {  
            serviceProviderProperties : {  
                URI : '/pluginwiris_engine/app/configurationjs',  
                server : 'java'  
            }  
        }  
    })  
    .then( /* ... */ )  
    .catch( /* ... */ );  
```

<a id="ckeditor5/latest/features/math-equations.html--php">

#### PHP

To install the PHP service, follow the steps below:

1. Download the [MathType Web Integration Services - PHP](https://store.wiris.com/en/products/downloads/mathtype/integrations) package.
2. Copy the `generic_wiris/integration` folder into your project. In this example, it was assumed the services are located at `DOCUMENT_ROOT/php-services/`.
3. Add `mathTypeParameters` to CKEditor 5 with the following configuration:  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        // MathType parameters.  
        mathTypeParameters : {  
            serviceProviderProperties : {  
                URI : 'http://localhost/php-services/integration',  
                server : 'php'  
            }  
        }  
    })  
.then( /* ... */ )  
.catch( /* ... */ );  
```

<a id="ckeditor5/latest/features/math-equations.html--net">

#### .NET

To install the .NET service, follow the steps below:

1. Download the [MathType Web Integration Services - Aspx](http://www.wiris.com/en/plugins/services/download) package.
2. Copy the `generic_wiris/integration` folder into your project. In this example, it was assumed the services are located at `DOCUMENT_ROOT/aspx-services/`.
3. Add `mathTypeParameters` to CKEditor 5 with this configuration:  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        // MathType parameters.  
        mathTypeParameters : {  
            serviceProviderProperties : {  
                URI : 'http://localhost/aspx-services/integration',  
                server : 'aspx'  
            }  
        }  
    })  
.then( /* ... */ )  
.catch( /* ... */ );  
```

<a id="ckeditor5/latest/features/math-equations.html--ruby-on-rails">

#### Ruby on Rails

To install the Ruby on Rails service, follow the steps below:

1. Download the [MathType Web Integration Services - Ruby on Rails](http://www.wiris.com/en/plugins/services/download) package.
2. Install the `wirispluginengine.gem` gem.  
```  
gem install -l wirispluginengine.gem  
```
3. Add `mathTypeParameters` to CKEditor 5 with the configuration below:  
```  
ClassicEditor  
    .create( {  
        // ... Other configuration options ...  
        // MathType parameters.  
        mathTypeParameters : {  
            serviceProviderProperties : {  
                URI : '/wirispluginengine/integrationn',  
                server : 'ruby'  
            }  
        }  
    })  
.then( /* ... */ )  
.catch( /* ... */ );  
```

<a id="ckeditor5/latest/features/math-equations.html--displaying-equations-on-your-website">

### Displaying equations on your website

By default, MathType returns equations in MathML which is [not supported by all browsers](https://developer.mozilla.org/en-US/docs/Web/MathML#browser%5Fcompatibility). To display equations on a page, you will need to use an engine that will handle the rendering process.

Fortunately, MathType introduces the full MathML mode that handles the unsupported markup and converts it into a form that can be properly recognized by browsers. You can read more about the full MathML mode [in the documentation](https://docs.wiris.com/mathtype-web-interface-features/full-mathml-mode-wirispluginsjs).

<a id="ckeditor5/latest/features/media-embed.html">source file: "ckeditor5/latest/features/media-embed.html"</a>

## Media embed

The media embed feature lets you insert embeddable media such as YouTube or Vimeo videos and tweets into your rich text content.

<a id="ckeditor5/latest/features/media-embed.html--demo">

### Demo

You can use the insert media button in the toolbar  to embed media. You can also paste a media URL directly into the editor content, and it will be [automatically embedded](#ckeditor5/latest/features/media-embed.html--automatic-media-embed-on-paste). Try both approaches with the following URLs:

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/media-embed.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/media-embed.html--previewable-and-non-previewable-media">

### Previewable and non-previewable media

When the media embed feature is asked to embed a specific media element via its URL it needs to make a decision how the media will be displayed in the editor.

<a id="ckeditor5/latest/features/media-embed.html--previewable-media">

#### Previewable media

If, for instance, the URL to embed is `https://www.youtube.com/watch?v=H08tGjXNHO4`, the feature can predict that it needs to produce the following HTML to show this YouTube video:

```
<div style="position: relative; padding-bottom: 100%; height: 0; padding-bottom: 56.2493%;">
    <iframe src="https://www.youtube.com/embed/${ videoId }"
        style="position: absolute; width: 100%; height: 100%; top: 0; left: 0;"
        frameborder="0" allow="autoplay; encrypted-media" allowfullscreen>
    </iframe>
</div>

```

Yes, it is quite complex, but this is the cost of creating responsive content for today’s web. The crucial part, though, is the iframe element’s `src` which the media embed feature can predict based on the given video URL and the aspect ratio (which affects `padding-bottom`).

Thanks to the ability to hardcode this URL to HTML transformation, the media embed feature can show previews of YouTube, Dailymotion, or Vimeo videos, and Spotify widgets without requesting any external service.

<a id="ckeditor5/latest/features/media-embed.html--non-previewable-media">

#### Non-previewable media

Unfortunately, to show previews of media such as tweets, Instagram photos, or Facebook posts, the editor would need to retrieve the content of these from an external service. Some of these media providers expose [oEmbed endpoints](https://oembed.com/) but not all. These endpoint responses often require further processing to be embeddable. Most importantly, though, the media embed feature is often not able to request these services due to the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin%5Fpolicy).

Also, the media embed feature [does not support asynchronous preview providers](https://github.com/ckeditor/ckeditor5-media-embed/issues/16) yet. Therefore, to still allow embedding tweets or Instagram photos, we chose to:

1. Show a placeholder of the embedded media in the editor (see how a tweet is presented in the [demo](#ckeditor5/latest/features/media-embed.html--demo) above).
2. Produce a [semantic <oembed url="..."> tag](#ckeditor5/latest/features/media-embed.html--semantic-data-output-default) in the data output from the editor. This output makes it possible to later use proxy services to [display the content of these media on your website](#ckeditor5/latest/features/media-embed.html--displaying-embedded-media-on-your-website).

You can overcome these limitations with the help of proxy services like Iframely or Embedly. This is explained in the [configuration guide below](#ckeditor5/latest/features/media-embed.html--using-external-services-for-preview).

<a id="ckeditor5/latest/features/media-embed.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/media-embed.html--data-output-format">

#### Data output format

You can configure the data output format of the feature using the [config.mediaEmbed.previewsInData](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedConfig.html#member-previewsInData) option.

<a id="ckeditor5/latest/features/media-embed.html--semantic-data-output-default">

##### Semantic data output (default)

By default, the media embed feature outputs semantic `<oembed url="...">` tags for previewable and non-previewable media. That being so, it works best when the application processes (expands) the media on the server side or [directly in the frontend](#ckeditor5/latest/features/media-embed.html--displaying-embedded-media-on-your-website), preserving the versatile database representation:

```
<figure class="media">
    <oembed url="https://media-url"></oembed>
</figure>

```

You can achieve further customization of the semantic data output through the [config.mediaEmbed.elementName](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedConfig.html#member-elementName) configuration. As an example, if you set `elementName` to `o-embed`:

```
<figure class="media">
    <o-embed url="https://media-url"></o-embed>
</figure>

```

If `elementName` is overridden to something other than the default value, the existing `<oembed>` elements will still be shown for backward compatibility purposes.

<a id="ckeditor5/latest/features/media-embed.html--including-previews-in-data">

##### Including previews in data

Optionally, by setting `mediaEmbed.previewsInData` to `true` you can configure the media embed feature to output media in the same way they look in the editor. If the media element is “previewable”, the media preview (HTML) is saved to the database:

```
<figure class="media">
    <div data-oembed-url="https://media-url">
        <iframe src="https://media-preview-url"></iframe>
    </div>
</figure>

```

Currently, the preview is only available for content providers for which CKEditor 5 can predict the `<iframe>` code: YouTube, Vimeo, Dailymotion, Spotify, etc. For other providers like X (Twitter) or Instagram, the editor cannot produce an `<iframe>` code. It also does not allow retrieving this code from an external oEmbed service. Therefore, for non-previewable media, it produces the default semantic output:

```
<figure class="media">
    <oembed url="https://media-url"></oembed>
</figure>

```

This means that, unless you [limit the list of providers](#ckeditor5/latest/features/media-embed.html--media-providers) to only those which are previewable, you need to [make sure that the media are displayed on your website](#ckeditor5/latest/features/media-embed.html--displaying-embedded-media-on-your-website).

Read more about [non-previewable media](#ckeditor5/latest/features/media-embed.html--previewable-and-non-previewable-media).

<a id="ckeditor5/latest/features/media-embed.html--media-providers">

#### Media providers

CKEditor 5 comes with several supported media providers that you can extend or alter.

Names of providers **with previews**:

* `'dailymotion'`,
* `'spotify'`,
* `'youtube'`,
* `'vimeo'`.

Names of providers **without previews**:

* `'instagram'`,
* `'twitter'`,
* `'googleMaps'`,
* `'flickr'`,
* `'facebook'`.

<a id="ckeditor5/latest/features/media-embed.html--extending-media-providers">

##### Extending media providers

To extend the default list of providers, use [config.mediaEmbed.extraProviders](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedConfig.html#member-extraProviders).

<a id="ckeditor5/latest/features/media-embed.html--removing-media-providers">

##### Removing media providers

To remove certain providers, use [config.mediaEmbed.removeProviders](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedConfig.html#member-removeProviders).

For instance, to leave only the previewable providers, configure this feature as follows:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mediaEmbed: {
            removeProviders: [ 'instagram', 'twitter', 'googleMaps', 'flickr', 'facebook' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/media-embed.html--overriding-media-providers">

##### Overriding media providers

To override the default providers, use [config.mediaEmbed.providers](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedConfig.html#member-providers) and define your set according to the [provider syntax](../api/module%5Fmedia-embed%5Fmediaembedconfig-MediaEmbedProvider.html):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mediaEmbed: {
            providers: [
                {
                    // A URL regular expression or an array of URL regular expressions:
                    url: /^example\.com\/media\/(\w+)/,

                    // To be defined only if the media are previewable:
                    html: match => '...'
                },
                // More providers.
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

You can take inspiration from the default configuration of this feature. You can find it in <https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-media-embed/src/mediaembedediting.ts>

<a id="ckeditor5/latest/features/media-embed.html--using-external-services-for-preview">

### Using external services for preview

To get around the limitations of showing media embed previews, you can use services like [Iframely](https://iframely.com/). This will allow a rich preview of the content inside CKEditor 5\. By inserting an Iframely-hosted `<iframe>`, you can preview the content from hundreds of media providers.

Follow the [Iframely integration with CKEditor 5](https://iframely.com/docs/ckeditor) page for a detailed explanation. You can also check the final result in the demo below. If you are using ad-blocking software, it might also block the previews inside the editor.

<a id="ckeditor5/latest/features/media-embed.html--displaying-embedded-media-on-your-website">

### Displaying embedded media on your website

By default, the media embed feature produces output that does not contain previews of embedded media, called the [semantic output](#ckeditor5/latest/features/media-embed.html--semantic-data-output-default). This means that you need to transform the output `<oembed>` elements into real media on your target website.

There are many ways to do that. The simplest, plug-and-play solutions are described here. You can also implement this transformation as part of your backend service or you can use different services than described in this section.

<a id="ckeditor5/latest/features/media-embed.html--iframely">

#### Iframely

[Iframely](https://iframely.com) offers the [embed.js](https://iframely.com/docs/embedjs) library which converts [various media](https://iframely.com/docs/providers) URLs into rich previews. It works in the frontend and remains fully compatible with the output produced by CKEditor 5.

First, having [secured the API key](https://iframely.com/docs/allow-origins), load the `embed.js` library from the CDN into your website:

```
<head>
    ...
    <script charset="utf-8" src="//cdn.iframe.ly/embed.js?api_key={API KEY}"></script>
    ...
</head>

```

<a id="ckeditor5/latest/features/media-embed.html--semantic-data">

##### Semantic data

You can convert all `<oembed>` elements like the following X (Twitter) post produced by CKEditor 5:

```
<figure class="media">
    <oembed url="https://x.com/ckeditor/status/1021777799844126720"></oembed>
</figure>

```

using this short code snippet:

```
<script>
    document.querySelectorAll( 'oembed[url]' ).forEach( element => {
        iframely.load( element, element.attributes.url.value );
    } );
</script>

```

<a id="ckeditor5/latest/features/media-embed.html--non-semantic-data">

##### Non-semantic data

When you configure the feature to [include media previews](#ckeditor5/latest/features/media-embed.html--including-previews-in-data) in the output, you can still use Iframely for media embeds like the following one:

```
<figure class="media">
    <div data-oembed-url="https://x.com/ckeditor/status/1021777799844126720">
        [Media preview]
    </div>
</figure>

```

You can still convert this data by Iframely with just a few extra lines of code. To do that, in addition to the code snippet from the previous section, use a slightly longer code snippet that discards the media preview saved in the database before using `iframely.load()`:

```
<script>
    document.querySelectorAll( 'div[data-oembed-url]' ).forEach( element => {
        // Discard the static media preview from the database (empty the <div data-oembed-url="...">).
        while ( element.firstChild ) {
            element.removeChild( element.firstChild );
        }

        // Generate the media preview using Iframely.
        iframely.load( element, element.dataset.oembedUrl ) ;
    } );
</script>

```

<a id="ckeditor5/latest/features/media-embed.html--embedly">

#### Embedly

Just like Iframely, [Embedly](https://embed.ly) offers the client–side API which converts media URLs into rich previews.

To start using it, load the library from the CDN into your website:

```
<head>
    ...
    <script async charset="utf-8" src="//cdn.embedly.com/widgets/platform.js"></script>
    ...
</head>

```

<a id="ckeditor5/latest/features/media-embed.html--semantic-data-2">

##### Semantic data

You can convert `<oembed>` elements like the following Twitter (X) post produced by CKEditor 5:

```
<figure class="media">
    <oembed url="https://x.com/ckeditor/status/1021777799844126720"></oembed>
</figure>

```

using this code snippet:

```
<script>
    document.querySelectorAll( 'oembed[url]' ).forEach( element => {
        // Create the <a href="..." class="embedly-card"></a> element that Embedly uses
        // to discover the media.
        const anchor = document.createElement( 'a' );

        anchor.setAttribute( 'href', element.getAttribute( 'url' ) );
        anchor.className = 'embedly-card';

        element.appendChild( anchor );
    } );
</script>

```

Embedly automatically discovers links like `<a href="..." class="embedly-card"></a>` and replaces them with rich media previews.

<a id="ckeditor5/latest/features/media-embed.html--non-semantic-data-2">

##### Non-semantic data

In this case, the code is almost the same as with the semantic data but you should discard the media preview saved in the database before using Embedly to avoid code duplication:

```
<script>
    document.querySelectorAll( 'div[data-oembed-url]' ).forEach( element => {
        // Discard the static media preview from the database (empty the <div data-oembed-url="...">).
        while ( element.firstChild ) {
            element.removeChild( element.firstChild );
        }

        // Create the <a href="..." class="embedly-card"></a> element that Embedly uses
        // to discover the media.
        const anchor = document.createElement( 'a' );

        anchor.setAttribute( 'href', element.dataset.oembedUrl );
        anchor.className = 'embedly-card';

        element.appendChild( anchor );
    } );
</script>

```

<a id="ckeditor5/latest/features/media-embed.html--automatic-media-embed-on-paste">

### Automatic media embed on paste

By default, the [MediaEmbed](../api/module%5Fmedia-embed%5Fmediaembed-MediaEmbed.html) plugin loads the [AutoMediaEmbed](../api/module%5Fmedia-embed%5Fautomediaembed-AutoMediaEmbed.html) as a dependency.

The [AutoMediaEmbed](../api/module%5Fmedia-embed%5Fautomediaembed-AutoMediaEmbed.html) plugin recognizes media links in the pasted content and embeds them shortly after they are injected into the document to speed up the editing. Just like the “traditional” embedding (using the toolbar button), automatic embedding works for all media providers specified in the [configuration](#ckeditor5/latest/features/media-embed.html--media-providers).

If the automatic embedding was unexpected, for instance when the link was meant to remain in the content as text, undo the action (by clicking the “Undo” button in the toolbar or using the Ctrl/Cmd+Z keystrokes).

<a id="ckeditor5/latest/features/media-embed.html--styling-media-in-the-editor-content">

### Styling media in the editor content

While the editor comes with default styles for popular media providers like Facebook, Instagram or X, you can create additional styles for non-previewable media in your editor content to help users identify them.

<a id="ckeditor5/latest/features/media-embed.html--styling-non-previewable-media">

#### Styling non-previewable media

The HTML structure of every non-previewable media in the editor is as follows:

```
<figure class="media ck-widget" contenteditable="false">
    <div class="ck-media__wrapper" data-oembed-url="[ URL of the media ]">
        <div class="ck ck-reset_all ck-media__placeholder">
            <div class="ck-media__placeholder__icon">
                <svg class="ck ck-icon" ...>...</svg>
            </div>
            <a class="ck-media__placeholder__url" target="new" href="[ URL of the media]">
                <span class="ck-media__placeholder__url__text">[ URL of the media]</span>
            </a>
        </div>
    </div>
</figure>

```

For example, you can create a dedicated style for media coming from the [ckeditor.com](https://ckeditor.com) domain. To do that, you will need some additional styles included in your website.

First, you must hide the generic media icon displayed for non-previewable media:

```
.ck-media__wrapper[data-oembed-url*="ckeditor.com"] .ck-media__placeholder__icon * {
    display: none;
}

```

Then, give the media a distinctive background color:

```
.ck-media__wrapper[data-oembed-url*="ckeditor.com"] .ck-media__placeholder {
    background: hsl(282, 44%, 47%);
}

```

and introduce the custom icon identifying the media:

```
.ck-media__wrapper[data-oembed-url*="ckeditor.com"] .ck-media__placeholder__icon {
    background-image: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHdpZHRoPSIxMDFweCIgaGVpZ2h0PSIxMDFweCIgdmlld0JveD0iMCAwIDEwMSAxMDEiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+ICAgICAgICA8dGl0bGU+bG9nby1lY29zeXN0ZW0tM2NhYTI3MDIxODwvdGl0bGU+ICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPiAgICA8ZGVmcz48L2RlZnM+ICAgIDxnIGlkPSJQYWdlLTEiIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPiAgICAgICAgPGcgaWQ9ImxvZ28tZWNvc3lzdGVtLTNjYWEyNzAyMTgiIGZpbGw9IiNGRkZGRkYiIGZpbGwtcnVsZT0ibm9uemVybyI+ICAgICAgICAgICAgPHJlY3QgaWQ9IlJlY3RhbmdsZSIgZmlsbC1vcGFjaXR5PSIwIiB4PSIwIiB5PSIwIiB3aWR0aD0iMTAxIiBoZWlnaHQ9IjEwMSI+PC9yZWN0PiAgICAgICAgICAgIDxwYXRoIGQ9Ik02NC44LDM4Ljg5MTIzODIgQzY2LjEwODU1MzgsMzkuOTE3NzU4MiA2Ny43MjMxODI2LDQwLjQ3MzI5MyA2OS4zODQ0NTk1LDQwLjQ2ODU4MzQgQzczLjQzMTIxNjIsNDAuNDY4NTgzNCA3Ni43MTE1MTM1LDM3LjI1Nzc4MTkgNzYuNzExNTEzNSwzMy4yOTUwOTE4IEM3Ni43MTE1MTM1LDI5LjMzMzAyNTIgNzMuNDMxMjE2MiwyNi4xMjA5NzY4IDY5LjM4NDQ1OTUsMjYuMTIwOTc2OCBDNjUuMzM3NzAyNywyNi4xMjA5NzY4IDYyLjA1ODAyNywyOS4zMzMwMjUyIDYyLjA1ODAyNywzMy4yOTUwOTE4IEM2Mi4wNTgwMjcsMzQuMzY0MzE5OSA2Mi4yOTY3Mjk3LDM1LjM3ODY4MzggNjIuNzI1MDI3LDM2LjI5MDE3NzMgTDU4LjM3MzA1NDEsNDAuNTUwODc5NyBDNTYuMjU3MjU2OCwzOS4xMjEwNDg1IDUzLjc2MjYxNjcsMzguMzYwMzA1NSA1MS4yMTEzNTE0LDM4LjM2NjkxMTIgQzQ4LjMzMzg2NDksMzguMzY2OTExMiA0NS42ODIwMjcsMzkuMzEwODI0NSA0My41NjEwNTQxLDQwLjg5OTM5MTkgTDM5LjY1NjY0ODYsMzcuMDc2MzU2MSBDNDAuMzc1NDcxNiwzNS45NDcwNDM1IDQwLjc1Njg0NDgsMzQuNjM0OTA3OSA0MC43NTU2NzU3LDMzLjI5NTA5MTggQzQwLjc1NTY3NTcsMjkuMzMzMDI1MiAzNy40NzUzNzg0LDI2LjEyMDk3NjggMzMuNDI4NjIxNiwyNi4xMjA5NzY4IEMyOS4zODE4NjQ5LDI2LjEyMDk3NjggMjYuMTAxNTY3NiwyOS4zMzMwMjUyIDI2LjEwMTU2NzYsMzMuMjk1MDkxOCBDMjYuMTAxNTY3NiwzNy4yNTcxNTg1IDI5LjM4MTg2NDksNDAuNDY5MjA2OSAzMy40Mjg2MjE2LDQwLjQ2OTIwNjkgQzM0Ljg0NTkxODksNDAuNDY5MjA2OSAzNi4xNjkzNTE0LDQwLjA3NTE4MjMgMzcuMjkwMTM1MSwzOS4zOTMxMjA4IEw0MS4xOTUxNjIyLDQzLjIxNjE1NjYgQzM5LjU3MjcyOTcsNDUuMjkyODkwNSAzOC42MDc5NzMsNDcuODg5NTg3MiAzOC42MDc5NzMsNTAuNzA2OTg3NiBDMzguNjA2NjIzNyw1My4yMjAyMjEzIDM5LjM4NjcwNSw1NS42NzEzMjggNDAuODM5NTk0Niw1Ny43MTkwMDM5IEwzNi40ODcsNjEuOTgwMzI5NyBDMzUuNTI1MTEwNSw2MS41NDc5NzY5IDM0LjQ4MjY4OTMsNjEuMzI1Mjc3MyAzMy40Mjg2MjE2LDYxLjMyNjk0NzIgQzI5LjM4MTg2NDksNjEuMzI2OTQ3MiAyNi4xMDE1Njc2LDY0LjUzODk5NTYgMjYuMTAxNTY3Niw2OC41MDEwNjIzIEMyNi4xMDE1Njc2LDcyLjQ2Mzc1MjQgMjkuMzgxODY0OSw3NS42NzUxNzczIDMzLjQyODYyMTYsNzUuNjc1MTc3MyBDMzcuNDc1Mzc4NCw3NS42NzUxNzczIDQwLjc1NTY3NTcsNzIuNDYzNzUyNCA0MC43NTU2NzU3LDY4LjUwMTA2MjMgQzQwLjc1NTY3NTcsNjYuODAyMTQzIDQwLjE1MjcwMjcsNjUuMjQxMDA3NyAzOS4xNDM4MTA4LDY0LjAxMjE3NDggTDQzLjA5MjM1MTQsNjAuMTQ2MTIwNCBDNDUuMjg1NDMyNCw2MS45NTYwMTQ5IDQ4LjExODE2MjIsNjMuMDQ3MDY0IDUxLjIxMDcyOTcsNjMuMDQ3MDY0IEM1NC4wODg4Mzc4LDYzLjA0NzA2NCA1Ni43NDAwNTQxLDYyLjEwMzE1MDcgNTguODYxNjQ4Niw2MC41MTM5NTk4IEw2My4xNTcwNTQxLDY0LjcxOTc5OCBDNjIuNDM4MjMxMSw2NS44NDkxMTA2IDYyLjA1Njg1NzksNjcuMTYxMjQ2MiA2Mi4wNTgwMjcsNjguNTAxMDYyMyBDNjIuMDU4MDI3LDcyLjQ2Mzc1MjQgNjUuMzM4MzI0Myw3NS42NzUxNzczIDY5LjM4NDQ1OTUsNzUuNjc1MTc3MyBDNzMuNDMxMjE2Miw3NS42NzUxNzczIDc2LjcxMTUxMzUsNzIuNDYzNzUyNCA3Ni43MTE1MTM1LDY4LjUwMTA2MjMgQzc2LjcxMTUxMzUsNjQuNTM4OTk1NiA3My40MzEyMTYyLDYxLjMyNjk0NzIgNjkuMzg0NDU5NSw2MS4zMjY5NDcyIEM2Ny45NjcxNjIyLDYxLjMyNjk0NzIgNjYuNjQ0MzUxNCw2MS43MjA5NzE4IDY1LjUyMjk0NTksNjIuNDAzNjU2OCBMNjEuMjI3NTQwNSw1OC4xOTc4MTg2IEM2Mi44NDk5NzMsNTYuMTIwNDYxMiA2My44MTQxMDgxLDUzLjUyMzc2NDUgNjMuODE0MTA4MSw1MC43MDY5ODc2IEM2My44MTQxMDgxLDQ3LjY3ODIzNTUgNjIuNzAwMTYyMiw0NC45MDUxMDA1IDYwLjg1MTQ1OTUsNDIuNzU3OTE2IEw2NC44LDM4Ljg5MTIzODIgWiBNNTUuOTc5MTg5MiwxLjMwNjc4MDg3IEw5Mi4wMjA4MTA4LDIxLjY4MDcxODkgQzk1LjEwMTU2NzYsMjMuNDIyNjU2NiA5NywyNi42NDIxODY1IDk3LDMwLjEyNjA2MTkgTDk3LDcwLjg3MzkzODEgQzk3LDc0LjM1NzgxMzUgOTUuMTAxNTY3Niw3Ny41NzczNDM0IDkyLjAyMDgxMDgsNzkuMzE5MjgxMSBMNTUuOTc5MTg5Miw5OS42OTM4NDI2IEM1Mi44ODY4MTA4LDEwMS40MzUzODYgNDkuMTEzMTg5MiwxMDEuNDM1Mzg2IDQ2LjAyMDgxMDgsOTkuNjkzODQyNiBMOS45NzkxODkxOSw3OS4zMTkyODExIEM2Ljg5ODQzMjQzLDc3LjU3NzM0MzQgNSw3NC4zNTc4MTM1IDUsNzAuODczOTM4MSBMNSwzMC4xMjYwNjE5IEM1LDI2LjY0MjE4NjUgNi44OTg0MzI0MywyMy40MjI2NTY2IDkuOTc5MTg5MTksMjEuNjgwNzE4OSBMNDYuMDIwODEwOCwxLjMwNjE1NzQxIEM0OS4xMTMxODkyLC0wLjQzNTM4NTgwMyA1Mi44ODY4MTA4LC0wLjQzNTM4NTgwMyA1NS45NzkxODkyLDEuMzA2MTU3NDEgTDU1Ljk3OTE4OTIsMS4zMDY3ODA4NyBaIE01MS4yMTEzNTE0LDU5Ljc5NjM2MTMgQzQ2LjA4NDIxNjIsNTkuNzk2MzYxMyA0MS45MjgwNTQxLDU1LjcyNzA2MDEgNDEuOTI4MDU0MSw1MC43MDYzNjQxIEM0MS45MjgwNTQxLDQ1LjY4NjkxNTEgNDYuMDg0MjE2Miw0MS42MTY5OTA0IDUxLjIxMTM1MTQsNDEuNjE2OTkwNCBDNTYuMzM4NDg2NSw0MS42MTY5OTA0IDYwLjQ5NDY0ODYsNDUuNjg2OTE1MSA2MC40OTQ2NDg2LDUwLjcwNjk4NzYgQzYwLjQ5NDY0ODYsNTUuNzI3MDYwMSA1Ni4zMzg0ODY1LDU5Ljc5Njk4NDcgNTEuMjExMzUxNCw1OS43OTY5ODQ3IEw1MS4yMTEzNTE0LDU5Ljc5NjM2MTMgWiBNNjkuMzg0NDU5NSw3Mi40MjUwOTgxIEM2Ny4xNzE0ODY1LDcyLjQyNTA5ODEgNjUuMzc3NDg2NSw3MC42NjgxOTc0IDY1LjM3NzQ4NjUsNjguNTAxMDYyMyBDNjUuMzc3NDg2NSw2Ni4zMzQ1NTA2IDY3LjE3MTQ4NjUsNjQuNTc3NjQ5OSA2OS4zODQ0NTk1LDY0LjU3NzY0OTkgQzcxLjU5NzQzMjQsNjQuNTc3NjQ5OSA3My4zOTIwNTQxLDY2LjMzNDU1MDYgNzMuMzkyMDU0MSw2OC41MDEwNjIzIEM3My4zOTIwNTQxLDcwLjY2ODE5NzQgNzEuNTk4MDU0MSw3Mi40MjUwOTgxIDY5LjM4NDQ1OTUsNzIuNDI1MDk4MSBaIE0zMy40Mjg2MjE2LDcyLjQyNTA5ODEgQzMxLjIxNTY0ODYsNzIuNDI1MDk4MSAyOS40MjE2NDg2LDcwLjY2ODE5NzQgMjkuNDIxNjQ4Niw2OC41MDEwNjIzIEMyOS40MjE2NDg2LDY2LjMzNDU1MDYgMzEuMjE1NjQ4Niw2NC41Nzc2NDk5IDMzLjQyODYyMTYsNjQuNTc3NjQ5OSBDMzUuNjQxNTk0Niw2NC41Nzc2NDk5IDM3LjQzNTU5NDYsNjYuMzM0NTUwNiAzNy40MzU1OTQ2LDY4LjUwMTA2MjMgQzM3LjQzNTU5NDYsNzAuNjY4MTk3NCAzNS42NDE1OTQ2LDcyLjQyNTA5ODEgMzMuNDI4NjIxNiw3Mi40MjUwOTgxIFogTTMzLjQyODYyMTYsMzcuMjE4NTA0MiBDMzEuMjE1NjQ4NiwzNy4yMTg1MDQyIDI5LjQyMTY0ODYsMzUuNDYyMjI2OSAyOS40MjE2NDg2LDMzLjI5NTA5MTggQzI5LjQyMTY0ODYsMzEuMTI3OTU2NyAzMS4yMTU2NDg2LDI5LjM3MTY3OTUgMzMuNDI4NjIxNiwyOS4zNzE2Nzk1IEMzNS42NDE1OTQ2LDI5LjM3MTY3OTUgMzcuNDM1NTk0NiwzMS4xMjc5NTY3IDM3LjQzNTU5NDYsMzMuMjk1MDkxOCBDMzcuNDM1NTk0NiwzNS40NjIyMjY5IDM1LjY0MTU5NDYsMzcuMjE4NTA0MiAzMy40Mjg2MjE2LDM3LjIxODUwNDIgWiBNNjkuMzg0NDU5NSwzNy4yMTg1MDQyIEM2Ny4xNzE0ODY1LDM3LjIxODUwNDIgNjUuMzc3NDg2NSwzNS40NjIyMjY5IDY1LjM3NzQ4NjUsMzMuMjk1MDkxOCBDNjUuMzc3NDg2NSwzMS4xMjc5NTY3IDY3LjE3MTQ4NjUsMjkuMzcxNjc5NSA2OS4zODQ0NTk1LDI5LjM3MTY3OTUgQzcxLjU5NzQzMjQsMjkuMzcxNjc5NSA3My4zOTIwNTQxLDMxLjEyNzk1NjcgNzMuMzkyMDU0MSwzMy4yOTUwOTE4IEM3My4zOTIwNTQxLDM1LjQ2MjIyNjkgNzEuNTk4MDU0MSwzNy4yMTg1MDQyIDY5LjM4NDQ1OTUsMzcuMjE4NTA0MiBaIiBpZD0iU2hhcGUiPjwvcGF0aD4gICAgICAgIDwvZz4gICAgPC9nPjwvc3ZnPg==);
}

```

Finally, make sure the URL in the placeholder has the right contrast:

```
.ck-media__wrapper[data-oembed-url*="ckeditor.com"] .ck-media__placeholder__url .ck-media__placeholder__url__text {
    color: hsl(282, 100%, 93%);
}

.ck-media__wrapper[data-oembed-url*="ckeditor.com"] .ck-media__placeholder__url .ck-media__placeholder__url__text:hover {
    color: hsl(0, 100%, 100%);
}

```

Before you load the data, make sure the `ckeditor.com` provider is [enabled in your configuration](#ckeditor5/latest/features/media-embed.html--extending-media-providers). In its most basic form it could look like this:

```
mediaEmbed: {
    extraProviders: [
        {
            name: 'ckeditor',
            url: /^ckeditor\.com/
        }
    ]
}

```

Having your styles defined and the media provider configured, insert the new media into your editor, for example, the following URL: `https://ckeditor.com/path/to/media`. You should see something like this:

<a id="ckeditor5/latest/features/media-embed.html--common-api">

### Common API

The [MediaEmbed](../api/module%5Fmedia-embed%5Fmediaembed-MediaEmbed.html) plugin registers:

* the `'mediaEmbed'` UI button component,
* the `'mediaEmbed'` command implemented by [MediaEmbedCommand](../api/module%5Fmedia-embed%5Fmediaembedcommand-MediaEmbedCommand.html).  
You can insert a new media element or update the selected media URL by executing the following code:  
```  
editor.execute( 'mediaEmbed', 'http://url.to.the/media' );  
```

<a id="ckeditor5/latest/features/media-embed.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-media-embed>.

<a id="ckeditor5/latest/features/mentions.html">source file: "ckeditor5/latest/features/mentions.html"</a>

## Mentions (autocompletion)

The mention feature enables smart autocompletion based on user input. When you type a pre-configured marker, such as `@` or `#`, a panel displays with autocomplete suggestions.

<a id="ckeditor5/latest/features/mentions.html--demo">

### Demo

You can type the “@” character to invoke the mention autocomplete UI. The demo below is configured to suggest a static list of names (`Barney`, `Lily`, `Marry Ann`, `Marshall`, `Robin`, and `Ted`).

You can read more about possible implementations of the mention feature in a [dedicated blog post](https://ckeditor.com/blog/mentions-in-ckeditor-5-feature-of-the-month/).

<a id="ckeditor5/latest/features/mentions.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/mentions.html--configuration">

### Configuration

The minimal configuration of the mention feature requires defining a [feed](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html) and a [marker](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html). You can also define the `minimumCharacters` parameter, setting the number of letters after which the autocomplete panel will show up. Moreover, feed items’ IDs may include whitespaces.

The code snippet below was used to configure the demo above. It defines the list of names that the editor will autocomplete after the user types the “@” character.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mention: {
            feeds: [
                {
                    marker: '@',
                    feed: [ '@Barney', '@Lily', '@Marry Ann', '@Marshall', '@Robin', '@Ted' ],
                    minimumCharacters: 1
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Additionally, you can configure:

* How the item is rendered in the autocomplete panel (via setting [itemRenderer](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html)). See [Customizing the autocomplete list](#ckeditor5/latest/features/mentions.html--customizing-the-autocomplete-list).
* How the item is converted during the [conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion). See [Customizing the output](#ckeditor5/latest/features/mentions.html--customizing-the-output).
* Multiple feeds. The demo above uses only one feed, which is triggered by the `'@'` character. You can define multiple feeds but they must use different markers. For example, you can use `'@'` for people and `'#'` for tags.

<a id="ckeditor5/latest/features/mentions.html--providing-the-feed">

#### Providing the feed

The [feed](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html) can be provided as:

* A static array – Good for scenarios with a relatively small set of autocomplete items.
* A callback – Provides more control over the returned list of items.

When using a callback you can return a `Promise` that resolves with the list of [matching feed items](../api/module%5Fmention%5Fmentionconfig-MentionFeedItem.html). These can be simple strings or plain objects with at least the `name` property. The other properties of this object can later be used when [customizing the autocomplete list](#ckeditor5/latest/features/mentions.html--customizing-the-autocomplete-list) or [customizing the output](#ckeditor5/latest/features/mentions.html--customizing-the-output).

The callback receives the query text which should be used to filter item suggestions. It should return a `Promise` and resolve it with an array of items that match the feed text.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mention: {
            feeds: [
                {
                    marker: '@',
                    feed: getFeedItems
                }
            }
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

const items = [
    { id: '@swarley', userId: '1', name: 'Barney Stinson', link: 'https://www.imdb.com/title/tt0460649/characters/nm0000439' },
    { id: '@lilypad', userId: '2', name: 'Lily Aldrin', link: 'https://www.imdb.com/title/tt0460649/characters/nm0004989' },
    { id: '@marry', userId: '3', name: 'Marry Ann Lewis', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
    { id: '@marshmallow', userId: '4', name: 'Marshall Eriksen', link: 'https://www.imdb.com/title/tt0460649/characters/nm0781981' },
    { id: '@rsparkles', userId: '5', name: 'Robin Scherbatsky', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
    { id: '@tdog', userId: '6', name: 'Ted Mosby', link: 'https://www.imdb.com/title/tt0460649/characters/nm1102140' }
];

function getFeedItems( queryText ) {
    // As an example of an asynchronous action, return a promise
    // that resolves after a 100ms timeout.
    // This can be a server request or any sort of delayed action.
    return new Promise( resolve => {
        setTimeout( () => {
            const itemsToDisplay = items
                // Filter out the full list of all items to only those matching the query text.
                .filter( isItemMatching )
                // Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
                .slice( 0, 10 );

            resolve( itemsToDisplay );
        }, 100 );
    } );

    // Filtering function - it uses the `name` and `username` properties of an item to find a match.
    function isItemMatching( item ) {
        // Make the search case-insensitive.
        const searchString = queryText.toLowerCase();

        // Include an item in the search results if the name or username includes the current user input.
        return (
            item.name.toLowerCase().includes( searchString ) ||
            item.id.toLowerCase().includes( searchString )
        );
    }
}

```

A full, working demo with all possible customizations and its source code is available [at the end of this section](#ckeditor5/latest/features/mentions.html--fully-customized-mention-feed).

<a id="ckeditor5/latest/features/mentions.html--customizing-the-autocomplete-list">

#### Customizing the autocomplete list

<a id="ckeditor5/latest/features/mentions.html--styling">

##### Styling

The items displayed in the autocomplete list can be customized by defining the [itemRenderer](../api/module%5Fmention%5Fmentionconfig-MentionFeed.html) callback.

This callback takes a feed item (it contains at least the `name` property) and must return a new DOM element.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mention: {
            feeds: [
                {
                    feed: [ /* ... */ ],
                    // Define the custom item renderer.
                    itemRenderer: customItemRenderer
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

function customItemRenderer( item ) {
    const itemElement = document.createElement( 'span' );

    itemElement.classList.add( 'custom-item' );
    itemElement.id = `mention-list-item-id-${ item.userId }`;
    itemElement.textContent = `${ item.name } `;

    const usernameElement = document.createElement( 'span' );

    usernameElement.classList.add( 'custom-item-username' );
    usernameElement.textContent = item.id;

    itemElement.appendChild( usernameElement );

    return itemElement;
}

```

A full, working demo with all possible customizations and its source code is available [at the end of this section](#ckeditor5/latest/features/mentions.html--fully-customized-mention-feed).

<a id="ckeditor5/latest/features/mentions.html--list-length">

##### List length

The number of items displayed in the autocomplete list can be customized by defining the [dropdownLimit](../api/module%5Fmention%5Fmentionconfig-MentionConfig.html#member-dropdownLimit) option.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mention: {
            // Define the custom number of visible mentions.
            dropdownLimit: 4
            feeds: [
                { /* ... */ }
                // More feeds.
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

A full, working demo with all possible customizations and its source code is available [at the end of this section](#ckeditor5/latest/features/mentions.html--fully-customized-mention-feed).

<a id="ckeditor5/latest/features/mentions.html--customizing-the-text-inserted-into-the-editor">

#### Customizing the text inserted into the editor

You can control the text inserted into the editor when creating a mention via the [text](../api/module%5Fmention%5Fmentionconfig-MentionFeedObjectItem.html) property in the mention configuration.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mention: {
            feeds: [
                // Feed items as objects.
                {
                    marker: '@',
                    feed: [
                        {
                            id: '@Barney',
                            fullName: 'Barney Stinson',
                            // Custom text to be inserted into the editor
                            text: 'Swarley'
                        },
                        // ...
                    ]
                },
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The string that you specify in this property will be displayed in the editor when a mention is created.

<a id="ckeditor5/latest/features/mentions.html--customizing-the-output">

#### Customizing the output

To change the markup generated by the editor for mentions, you can overwrite the default converter of the mention feature. To do that, you must specify both [upcast](../api/module%5Fengine%5Fconversion%5Fupcastdispatcher-UpcastDispatcher.html) and [downcast](../api/module%5Fengine%5Fconversion%5Fdowncastdispatcher-DowncastDispatcher.html) converters using [ViewAttributeElement](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html).

The example below defines a plugin that overrides the default output:

```
<span data-mention="@Ted" class="mention">@Ted</span>

```

To a link:

```
<a class="mention" data-mention="@Ted" data-user-id="5" href="https://www.imdb.com/title/tt0460649/characters/nm1102140">@tdog</a>

```

The converters must be defined with a `'high'` priority to be executed before the [link](#ckeditor5/latest/features/link.html) feature’s converter and before the default converter of the mention feature. A mention is stored in the model as a [text attribute](#ckeditor5/latest/framework/architecture/editing-engine.html--text-attributes) that stores an object (see [MentionFeedItem](../api/module%5Fmention%5Fmentionconfig-MentionFeedItem.html)).

To control how the mention element is wrapped by other attribute elements (like bold, italic, etc) set its [priority](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html#member-priority). To replicate default plugin behavior and make mention to be wrapped by other elements set priority to `20`.

By default, attribute elements that are next to each other and have the same value will be rendered as a single HTML element. To prevent this, the model attribute value object exposes a unique ID of each inserted mention to the model as `uid`. To prevent merging subsequent mentions, set it as [id](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html#member-id). The `uid` is persisted in the data output as the `data-mention-uid` attribute to guarantee that the same HTML always produces the same model. During clipboard (copy/cut) output, `data-mention-uid` is omitted so that pasted mentions receive fresh unique IDs.

**Note:** The feature prevents copying fragments of existing mentions. If only a part of a mention is selected, it will be copied as plain text. The internal converter with the ['highest' priority](../api/module%5Futils%5Fpriorities-PrioritiesType.html#member-highest) controls this behavior. We do not recommend adding mention converters with the `'highest'` priority to avoid collisions and quirky results.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [ Mention, MentionCustomization, /* ... */ ], // Add the custom mention plugin function.
        mention: {
            // Configuration.
            // ...
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

function MentionCustomization( editor ) {
    // The upcast converter will convert view <a class="mention" href="" data-user-id="">
    // elements to the model 'mention' text attribute.
    editor.conversion.for( 'upcast' ).elementToAttribute( {
        view: {
            name: 'a',
            key: 'data-mention',
            classes: 'mention',
            attributes: {
                href: true,
                'data-user-id': true
            }
        },
        model: {
            key: 'mention',
            value: viewItem => {
                // The mention feature expects that the mention attribute value
                // in the model is a plain object with a set of additional attributes.
                // In order to create a proper object use the toMentionAttribute() helper method:
                const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
                    // Add any other properties that you need.
                    link: viewItem.getAttribute( 'href' ),
                    userId: viewItem.getAttribute( 'data-user-id' )
                } );

                return mentionAttribute;
            }
        },
        converterPriority: 'high'
    } );

    // Downcast the model 'mention' text attribute to a view <a> element.
    editor.conversion.for( 'downcast' ).attributeToElement( {
        model: 'mention',
        view: ( modelAttributeValue, { writer, options } ) => {
            // Do not convert empty attributes (lack of value means no mention).
            if ( !modelAttributeValue ) {
                return;
            }

            return writer.createAttributeElement( 'a', {
                class: 'mention',
                'data-mention': modelAttributeValue.id,
                'data-user-id': modelAttributeValue.userId,
                'href': modelAttributeValue.link,
                // Omit `data-mention-uid` in clipboard (copy/cut) to prevent UIDs duplication.
                ...( !options.isClipboardPipeline && { 'data-mention-uid': modelAttributeValue.uid } )
            }, {
                // Make mention attribute to be wrapped by other attribute elements.
                priority: 20,
                // Prevent merging mentions together in clipboard (when `data-mention-uid` is not available).
                id: modelAttributeValue.uid
            } );
        },
        converterPriority: 'high'
    } );
}

```

A full, working demo with all possible customizations and its source code is available [at the end of this section](#ckeditor5/latest/features/mentions.html--fully-customized-mention-feed).

<a id="ckeditor5/latest/features/mentions.html--fully-customized-mention-feed">

#### Fully customized mention feed

Below is an example of a customized mention feature that:

* Uses a feed of items with additional properties (`id`, `username`, `link`).
* Renders custom item views in the autocomplete panel.
* Converts a mention to an `<a>` element instead of a `<span>`.
* Limits the number of mentions to four elements.

<a id="ckeditor5/latest/features/mentions.html--source-code">

##### Source code

```
ClassicEditor
    .create( {
        attachTo: document.querySelector( '#snippet-mention-customization' ),
        // ... Other configuration options ...
        plugins: [ Mention, MentionCustomization, /* ... */ ],
        mention: {
            dropdownLimit: 4,
            feeds: [
                {
                    marker: '@',
                    feed: getFeedItems,
                    itemRenderer: customItemRenderer
                }
            ]
        }
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( err => {
        console.error( err.stack );
    } );

function MentionCustomization( editor ) {
    // The upcast converter will convert <a class="mention" href="" data-user-id="">
    // elements to the model 'mention' attribute.
    editor.conversion.for( 'upcast' ).elementToAttribute( {
        view: {
            name: 'a',
            key: 'data-mention',
            classes: 'mention',
            attributes: {
                href: true,
                'data-user-id': true
            }
        },
        model: {
            key: 'mention',
            value: viewItem => {
                // The mention feature expects that the mention attribute value
                // in the model is a plain object with a set of additional attributes.
                // In order to create a proper object, use the toMentionAttribute helper method:
                const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
                    // Add any other properties that you need.
                    link: viewItem.getAttribute( 'href' ),
                    userId: viewItem.getAttribute( 'data-user-id' )
                } );

                return mentionAttribute;
            }
        },
        converterPriority: 'high'
    } );

    // Downcast the model 'mention' text attribute to a view <a> element.
    editor.conversion.for( 'downcast' ).attributeToElement( {
        model: 'mention',
        view: ( modelAttributeValue, { writer, options } ) => {
            // Do not convert empty attributes (lack of value means no mention).
            if ( !modelAttributeValue ) {
                return;
            }

            return writer.createAttributeElement( 'a', {
                class: 'mention',
                'data-mention': modelAttributeValue.id,
                'data-user-id': modelAttributeValue.userId,
                'href': modelAttributeValue.link,
                // Omit `data-mention-uid` in clipboard (copy/cut) to prevent UIDs duplication.
                ...( !options.isClipboardPipeline && { 'data-mention-uid': modelAttributeValue.uid } )
            }, {
                // Make mention attribute to be wrapped by other attribute elements.
                priority: 20,
                // Prevent merging mentions together in clipboard (when `data-mention-uid` is not available).
                id: modelAttributeValue.uid
            } );
        },
        converterPriority: 'high'
    } );
}

const items = [
    { id: '@swarley', userId: '1', name: 'Barney Stinson', link: 'https://www.imdb.com/title/tt0460649/characters/nm0000439' },
    { id: '@lilypad', userId: '2', name: 'Lily Aldrin', link: 'https://www.imdb.com/title/tt0460649/characters/nm0004989' },
    { id: '@marry', userId: '3', name: 'Marry Ann Lewis', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
    { id: '@marshmallow', userId: '4', name: 'Marshall Eriksen', link: 'https://www.imdb.com/title/tt0460649/characters/nm0781981' },
    { id: '@rsparkles', userId: '5', name: 'Robin Scherbatsky', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
    { id: '@tdog', userId: '6', name: 'Ted Mosby', link: 'https://www.imdb.com/title/tt0460649/characters/nm1102140' }
];

function getFeedItems( queryText ) {
    // As an example of an asynchronous action, return a promise
    // that resolves after a 100ms timeout.
    // This can be a server request or any sort of delayed action.
    return new Promise( resolve => {
        setTimeout( () => {
            const itemsToDisplay = items
                // Filter out the full list of all items to only those matching the query text.
                .filter( isItemMatching )
                // Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
                .slice( 0, 10 );

            resolve( itemsToDisplay );
        }, 100 );
    } );

    // Filtering function - it uses `name` and `username` properties of an item to find a match.
    function isItemMatching( item ) {
        // Make the search case-insensitive.
        const searchString = queryText.toLowerCase();

        // Include an item in the search results if name or username includes the current user input.
        return (
            item.name.toLowerCase().includes( searchString ) ||
            item.id.toLowerCase().includes( searchString )
        );
    }
}

function customItemRenderer( item ) {
    const itemElement = document.createElement( 'span' );

    itemElement.classList.add( 'custom-item' );
    itemElement.id = `mention-list-item-id-${ item.userId }`;
    itemElement.textContent = `${ item.name } `;

    const usernameElement = document.createElement( 'span' );

    usernameElement.classList.add( 'custom-item-username' );
    usernameElement.textContent = item.id;

    itemElement.appendChild( usernameElement );

    return itemElement;
}

```

<a id="ckeditor5/latest/features/mentions.html--colors-and-styles">

#### Colors and styles

<a id="ckeditor5/latest/features/mentions.html--using-css-variables">

##### Using CSS variables

The mention feature uses the power of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using%5FCSS%5Fvariables) which are defined in the [default theme style sheet](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-mention/theme/mention.css). Thanks to that, mention styles can be [easily customized](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html):

```
:root {
    /* Make the mention background blue. */
    --ck-color-mention-background: hsla(220, 100%, 54%, 0.4);

    /* Make the mention text dark grey. */
    --ck-color-mention-text: hsl(0, 0%, 15%);
}

```

<a id="ckeditor5/latest/features/mentions.html--comments-with-mentions">

#### Comments with mentions

It is possible to configure the Mentions feature to work with the [Comments feature](#ckeditor5/latest/features/collaboration/comments/comments.html). Here you can find [detailed guidance on that matter](#ckeditor5/latest/features/collaboration/annotations/annotations-custom-configuration.html--comment-editor-configuration).

<a id="ckeditor5/latest/features/mentions.html--related-features">

### Related features

In addition to enabling mentions, you may want to check the following productivity features:

* [Automatic text transformation](#ckeditor5/latest/features/text-transformation.html) – Lets you automatically turn snippets such as `(tm)` into `™` and `"foo"` into `“foo”`.
* [Autolink](#ckeditor5/latest/features/link.html--autolink-feature) – Turns the links and email addresses typed or pasted into the editor into active URLs.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Lets you quickly apply formatting to the content you are writing.
* [Emoji](#ckeditor5/latest/features/emoji.html) – Lets you quickly insert desired emoji.

<a id="ckeditor5/latest/features/mentions.html--common-api">

### Common API

The [Mention](../api/module%5Fmention%5Fmention-Mention.html) plugin registers:

* The `'mention'` command implemented by [MentionCommand](../api/module%5Fmention%5Fmentioncommand-MentionCommand.html).  
You can insert a mention element by executing the following code:  
```  
editor.execute( 'mention', { marker: '@', mention: '@John' } );  
```

<a id="ckeditor5/latest/features/mentions.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-mention>.

<a id="ckeditor5/latest/features/merge-fields.html">source file: "ckeditor5/latest/features/merge-fields.html"</a>

## Merge fields

Merge fields are visually distinct placeholder elements, which you may put into the content to mark places, where real values should be inserted. This is perfect for creating document templates and other kinds of personalized content.

The feature is highly customizable, offers text, block and image placeholders, a preview mode, and is integrated with our document export and import plugins. Using these tools allows for highly efficient automation of mass document creation (especially in connection with [document export plugins](#ckeditor5/latest/features/merge-fields.html--document-export-plugins)). It can be employed to improve efficiency, shorten the production time, and optimize the workflow.

Below we present the typical use cases for the feature. Choose the setup that fits your needs the best.

<a id="ckeditor5/latest/features/merge-fields.html--template-editing">

### Template editing

The most popular use case is creating templates of documents, e-mails, invoices, and other kinds of personalized content.

The user can insert one of the pre-configured merge field elements in various ways:

* from a toolbar dropdown ,
* from the menu bar, under “Insert” → “Merge field,”
* or by typing the opening bracket (`{{` by default), and choosing one of the merge fields from the list.

To enable this use case, simply configure the merge fields definitions and add a button to the toolbar.

You can learn more about configuring the feature in the Configuration section of this guide.

<a id="ckeditor5/latest/features/merge-fields.html--preview-mode">

### Preview mode

Enhance the template creation experience by defining example preview data sets.

As the user prepares the template, they will be able to switch to a data preview mode. In this mode, merge fields labels are replaced with values taken from the chosen data set. This way, the user will have a better understanding how the actual, final content may look like.

The default initial preview mode is “labels.” When the data for other preview modes is provided, the preview modes can be switched using a toolbar dropdown , or through the menu bar (“View” → “Merge fields preview”).

<a id="ckeditor5/latest/features/merge-fields.html--data-only-setup">

### Data-only setup

Instead of showing the labels, the editor can be configured to always display the merge fields values, without a way to switch it. The user will insert the merge fields into the content as previously, but they will always see the defined data.

This setup is perfect when you want to use a previously prepared template to create a concrete piece of content, in the context of a specific data set (for example customer data), possibly editing it along the way to further personalize the content.

Using merge fields in this configuration is useful even when you start from scratch! The user avoids typos and has convenient access to correct values, while the created document is always up-to-date, in case the related data set changes.

To enable this use case, use feature configuration to provide a data set, set the initial preview mode and disable other preview modes.

Apart from providing data sets, you can also define default values for the merge fields. The default value is used when the data set is missing a value for a given merge field. Additionally, an error indicator is displayed, to make the user aware of a possible problem. This is useful when you cannot guarantee that your data sets are always complete.

<a id="ckeditor5/latest/features/merge-fields.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/merge-fields.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/merge-fields.html--configuration">

### Configuration

To make the most out of the merge fields feature, it has to be properly configured. Some options (such as prefix and suffix or preview modes) have a reasonable default set, but it is essential to at least define the list of the available merge fields.

<a id="ckeditor5/latest/features/merge-fields.html--merge-fields-definitions">

#### Merge fields definitions

To make the merge fields appear in the editor UI you have to specify them in the [mergeFields.definitions](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-definitions) property.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mergeFields: {
            definitions: [
                {
                    id: 'guestName',
                    label: 'Guest name', // Optional.
                    defaultValue: 'Guest' // Optional.
                },
                {
                    id: 'guestSpecialOffersBox',
                    label: 'Special offers', // Optional.
                    type: 'block', // Optional.
                    height: 150 // Optional.
                },
                {
                    id: 'companyLogo',
                    label: 'Company logo', // Optional.
                    type: 'image', // Optional.
                    width: 300, // Optional.
                    height: 300 // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The merge field id is the only required value, and it is used in the document data returned by the editor. It may include letters, numbers and `_`, `.`, `-` special characters.

The merge field label is displayed in the editor, if defined. If not, the id is used instead.

[Custom (non-defined) merge fields](#ckeditor5/latest/features/merge-fields.html--custom-merge-fields) may be inserted into the document as well.

Use the [source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) toolbar button  in the [presented demos](#ckeditor5/latest/features/merge-fields.html--template-editing) to see an example of the editor output.

<a id="ckeditor5/latest/features/merge-fields.html--merge-field-type">

##### Merge field type

The feature supports three different types of merge fields:

1. Typical, inline, text merge fields, most often replaced by textual data. For example, a customer name or invoice number.
2. Block merge fields, which represent a bigger piece of content, replaced by an arbitrary HTML structure. For example, a row with box presenting top selling products or an email footer.
3. Image merge fields, which behave just like native images – they can be resized, align to the side etc.

You can define the merge field type using `type` property. Possible values are: `'text'` (default), `'block'` and `'image'`.

```
ClassicEditor
    .create( {
        mergeFields: {
            definitions: [
                {
                    id: 'guestAddress',
                    type: 'block',
                    label: 'Guest address' // Optional.
                },
                {
                    id: 'companyLogo',
                    type: 'image',
                    label: 'Company logo' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

In the editor, text merge fields are treated like text. They can be placed only where text is allowed, can be formatted, or be a link. Block merge fields behave like other block-level widgets, and can be placed only where blocks are allowed. Image merge fields behave like images and have identical features, like alternative text, resizing etc., but their `src` attribute is set to the merge field ID.

<a id="ckeditor5/latest/features/merge-fields.html--block-merge-fields">

###### Block merge fields

For block merge fields, it is possible to configure how much vertical space should they occupy. This makes it easier to better visualize how the actual content will look like, or predict the page breaks. Set it using the `height` property (150px by default). Note, that this setting is used only if data for given merge field is not displayed. In a preview mode, the merge field height will depend on the merge field content.

```
ClassicEditor
    .create( {
        mergeFields: {
            definitions: [
                {
                    id: 'guestAddress',
                    type: 'block',
                    height: '100', // In pixels. Defaults to 150.
                    label: 'Guest address' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

When it comes to document data, the block merge fields are not wrapped in any HTML structure. It is assumed that the merge field will be replaced by some block-level HTML structure. See example document data below:

```
    <p>
        See the order details below.
    </p>
    {{orderDetails}}
    <p>
        <!-- Further content. -->
    </p>

```

<a id="ckeditor5/latest/features/merge-fields.html--image-merge-fields">

###### Image merge fields

When defining an image merge field in the configuration, you should specify its width and height. Thanks to that it will have a proper aspect ratio and look well in the editor even if you decide to resize it. Set it using the `width` and `height` properties. Note, that this property is used only if data for given merge field is not displayed.

```
ClassicEditor
    .create( {
        mergeFields: {
            definitions: [
                {
                    id: 'companyLogo',
                    type: 'image',
                    width: 400, // In pixels.
                    height: 200, // In pixels.
                    label: 'Company logo' // Optional.
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

In the document data, the image merge fields are simply images with the `src` attribute value set to the merge field ID (`<img>` element is wrapped with the `<figure class="image"></figure>` element if it is a block image).

```
    <p>
        See the inline merge field image here: <img src="{{companyLogoSmall}}" />.
        And a block merge field image below:
    </p>
    <figure class="image"><img src="{{companyLogo}}" /></figure>
    <p>
        <!-- Further content. -->
    </p>

```

**Note:** If you want to load the image merge fields to the editor, you should use [config#initialData property](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData) to set the initial content. Otherwise, you may get warnings in the browser console.

<a id="ckeditor5/latest/features/merge-fields.html--grouping-merge-fields">

##### Grouping merge fields

To better organize the merge fields in the dropdown, you can divide the definitions into groups.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mergeFields: {
            definitions: [
                {
                    groupId: 'guest',
                    groupLabel: 'Guest',
                    definitions: [
                        {
                            id: 'guestName',
                            label: 'Guest name',
                            defaultValue: 'Guest'
                        },
                        {
                            id: 'guestTitle',
                            label: 'Guest title',
                            defaultValue: 'Ms./Mr.'
                        },
                        // More merge field definitions
                        // inside the "Guest" group.
                    ]
                },
                // More merge field groups.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/merge-fields.html--prefix-and-suffix">

#### Prefix and suffix

The [mergeFields.prefix](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-prefix) and [mergeFields.suffix](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-suffix) (characters combinations used to indicate the start and end of the merge field) can be configured as well. The defined values will be returned in the editor output.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        // Use different kind of brackets for merge fields indicators.
        mergeFields: {
            prefix: '[[',
            suffix: ']]'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The default merge fields brackets are `{{` and `}}`. The following characters are allowed in prefix and suffix: `` '"`!#%:;=@{}~$()*+/?[\]^| ``. Additionally, they cannot be longer than 8 characters.

**Note:** The prefix and suffix must be different.

**Note:** The brackets that are used in the stored document data will not automatically update after you change the `prefix` or `suffix` configuration. The change will affect only the newly inserted merge fields. Additionally, old merge fields will not be recognized and will be displayed as plain text. If you need to change brackets configuration, you should also process the document data for all documents created in your application so far.

<a id="ckeditor5/latest/features/merge-fields.html--preview-modes">

#### Preview modes

The preview modes change how the merge fields are displayed in the editor area. The editor may display either merge fields labels (or ids), or data values, for preview purposes.

To be able to change preview modes, you will need to define either [merge fields default values](#ckeditor5/latest/features/merge-fields.html--merge-fields-definitions) or [data sets](#ckeditor5/latest/features/merge-fields.html--data-sets) (described later on).

<a id="ckeditor5/latest/features/merge-fields.html--available-preview-modes">

##### Available preview modes

Use [mergeFields.previewModes](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-previewModes) configuration option to specify which preview modes should be available for the user. It should be specified as any combination of the three possible values:

* The “labels” view (`'$labels'` value) - displays labels (or ids, if not specified).
* The “default values” view (`'$defaultValues'`) - displays default values, if specified.
* All the configured data sets (`'$dataSets'`) - displays values for a chosen data set.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mergeFields: {
            // The user will be allowed only to switch between defined data sets,
            // and the merge fields will always display the data related to one of
            // the defined data sets. If there is only one data set, the user will
            // be forced to see the data from that set and will not be able to switch.
            previewModes: [ '$dataSets' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

**Note:** At least one option must be defined.

**Note:** If only one preview mode is available (meaning, the passed value is `[ '$labels' ]`, or `[ '$defaultValues' ]`, or `[ '$dataSets' ]` with only one data set defined), the “Merge fields preview” button will not be added to the “View” menu.

<a id="ckeditor5/latest/features/merge-fields.html--initial-preview-mode">

##### Initial preview mode

The [mergeFields.initialPreviewMode](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-initialPreviewMode) option specifies which preview mode should be active when the editor is loaded. By default, merge field labels will be shown.

The passed value can be either of: `'$labels'`, `'$defaultValues'`, or one of the IDs of the defined data sets.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mergeFields: {
            // ID of a data set (see an example below).
            initialPreviewMode: '158673'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

**Note:** The initial preview mode must be also specified as one of the [available preview modes](#ckeditor5/latest/features/merge-fields.html--available-preview-modes). Otherwise, an error will be thrown.

<a id="ckeditor5/latest/features/merge-fields.html--data-sets">

#### Data sets

To be able to preview data in place of merge fields, you must define at least one [data set](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-dataSets). A data set should define values according to defined merge fields ids. If some values are not available, the merge fields default value will be used instead (if defined).

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        mergeFields: {
            dataSets: [
                {
                    id: '158673',
                    label: 'David Lee',
                    values: {
                        guestName: 'David Lee',
                        guestTitle: 'Mr.'
                        // Other values in this data set.
                    }
                },
                // More data sets.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/merge-fields.html--dynamic-merge-fields-values">

#### Dynamic merge fields values

<a id="ckeditor5/latest/features/merge-fields.html--using-callbacks-to-define-values">

##### Using callbacks to define values

Some merge field values may require to be dynamically calculated, for example if they are based on other values. It can be achieved by defining a value (either a default one or in a data set) as a callback. The callback is executed when the merge field is inserted into a document, when a preview mode changes, or when document is exported to PDF or Word file.

For example, you can create a simple plugin fetching data when it is initialized:

```
class ExternalFetcher extends Plugin {
    static get pluginName {
        return 'ExternalFetcher';
    }

    mergeFieldsData = {};

    init() {
        this._setMergeFieldsData();
    }

    async _setMergeFieldsData() {
        const response = await fetch( externalUrl ); // Replace `externalUrl` with your data endpoint.

        // Adjust the data here if necessary, e.g. parse JSON or add time stamp.
        // You can expose it in `window` object, public plugin property, or through `localStorage`.
        this.mergeFieldsData = response;

        // Refresh the editor so it displays the updated merge fields values.
        this.editor.plugins.get( 'MergeFieldsEditing' ).refreshMergeFields();
    }
}

```

And define the merge field that will look for the data in that plugin property to calculate its default value (the editor instance is passed as the callback parameter):

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [ ExternalFetcher, /* ... */ ],
        mergeFields: {
            definitions: [
                {
                    id: 'bitcoinRate',
                    label: 'Bitcoin rate',
                    defaultValue: editor => {
                        if ( !editor.plugins.has( 'ExternalFetcher' ) ) {
                            return 'Data is not available';
                        }

                        return editor.plugins.get( 'ExternalFetcher' ).mergeFieldsData.bitcoinRate || 'Fetching data...'
                    }
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/merge-fields.html--refreshing-callbacks-values">

##### Refreshing callbacks values

If the merge field value comes from an external source, you may want to refresh it after it changes, so the editor displays correct values. You can use the [#refreshMergeFields()](../api/module%5Fmerge-fields%5Fmergefieldsediting-MergeFieldsEditing.html#function-refreshMergeFields) method to trigger recalculation of all the merge fields.

For example, if you want to refresh the values periodically, you can use `setInterval()`. First, create a similar plugin as before, but this time trigger the fetching function periodically to update the data for merge fields:

```
class IntervalFetcher extends Plugin {
    static get pluginName {
        return 'IntervalFetcher';
    }

    mergeFieldsData = {};

    init() {
        // Initial data setup.
        this._updateMergeFieldsData();

        // Updating data every 5 seconds.
        setInterval( () => this._updateMergeFieldsData(), 5000 )
    }

    async _updateMergeFieldsData() {
        const response = await fetch( externalUrl ); // Replace `externalUrl` with your data endpoint.

        // Adjust the data here if necessary.
        // You can expose it in `window` object, public plugin property, or through `localStorage`.
        this.mergeFieldsData = response;

        // Refresh the editor so it displays the updated merge fields values.
        this.editor.plugins.get( 'MergeFieldsEditing' ).refreshMergeFields();
    }
}

```

The merge field configuration will look the same as before:

```
ClassicEditor
    .create( {
        plugins: [ IntervalFetcher, /* ... */ ],
        mergeFields: {
            definitions: [
                {
                    id: 'bitcoinRate',
                    label: 'Bitcoin rate',
                    defaultValue: editor => {
                        if ( !editor.plugins.has( 'IntervalFetcher' ) ) {
                            return 'Data is not available';
                        }

                        editor.plugins.get( 'IntervalFetcher' ).mergeFieldsData.bitcoinRate || 'Fetching data...'
                    }
                },
                // More merge field definitions.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

In the demo below, the merge field containing the current Bitcoin rate will automatically update every 5 seconds.

<a id="ckeditor5/latest/features/merge-fields.html--using-html-tags-in-merge-fields-values">

#### Using HTML tags in merge fields values

It is possible to use HTML code inside merge fields values, both in default values and the data set values.

By default, this behavior is disabled and merge fields values will be treated as plain text (HTML tags will get encoded). To enable HTML merge fields values:

* set [config.mergeFields.previewHtmlValues](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-previewHtmlValues) configuration flag to `true`,
* provide an HTML sanitization function in [config.mergeFields.sanitizeHtml](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-sanitizeHtml) property.

**It is strongly recommended to provide an HTML sanitization function**.

If you enable HTML merge fields values, the HTML assigned to merge field will be rendered as-is when the user switches to the preview mode. As a result, **the browser will execute any JavaScript code included in this HTML in the context of your website**. This may lead to a security vulnerability, if the merge fields values are provided from an external source that cannot be fully trusted (for example users provide them in a different part of your application).

If you do not provide a sanitization function, a warning will be logged to the console.

You can provide your custom sanitization function or use one of the popular JavaScript libraries, like [sanitize-html](https://www.npmjs.com/package/sanitize-html) and [DOMPurify](https://www.npmjs.com/package/dompurify).

The default settings of these libraries usually strip all potentially malicious content including `<iframe>`, `<video>`, or similar elements, as well as JavaScript code. You may need to adjust their settings to match your needs.

<a id="ckeditor5/latest/features/merge-fields.html--integration">

### Integration

<a id="ckeditor5/latest/features/merge-fields.html--editor-data-output">

#### Editor data output

Merge fields are returned by [editor.getData()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) as the merge field id enclosed in the specified prefix and suffix, for example: `<p>Dear {{guestTitle}} {{guestName}}</p>`. It is an industry standard format for representing merge fields, which makes it convenient to replace the merge fields with actual data.

Use the [source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) toolbar button  in the [presented demos](#ckeditor5/latest/features/merge-fields.html--template-editing) to see an example of the editor output.

**Note:** Switching preview mode to display data set values **does not** affect the editor output. In most regular cases, you will always want to save the document data with the merge fields placeholders, not the values. The data replacement should happen in your application logic when needed.

<a id="ckeditor5/latest/features/merge-fields.html--data-output-with-filled-in-merge-fields">

#### Data output with filled-in merge fields

In some cases, it may be useful to get the document data with the merge fields replaced by some actual data.

You may pass the values as an option to `editor.getData()` call:

```
const data = editor.getData( {
    mergeFieldsData: {
        guestName: 'Joe Doe',
        guestTitle: 'Mr.'
    }
} );

```

And the editor will use these values in place of given merge fields.

If data for a given merge field is not specified, the default data form will be used (`[PREFIX][MERGE_FIELD_ID][SUFFIX]`, for example `{{guestName}}`).

Most likely, you will want to save the data with merge fields replaced by values from the currently previewed data set:

```
const mergeFieldsEditing = editor.plugins.get( 'MergeFieldsEditing' );

const mergeFieldsData = mergeFieldsEditing.getDataSetValues(
    mergeFieldsEditing.previewMode, true
);

const data = editor.getData( { mergeFieldsData } );

```

<a id="ckeditor5/latest/features/merge-fields.html--custom-merge-fields">

#### Custom merge fields

The editor will **convert every piece of text matching the merge field pattern to a merge field element**. This behavior cannot be currently turned off.

Please note, that from the point of view of the editor output, it is indifferent whether the merge field matching text is recognized by the editor, as both defined and custom merge fields are represented the same in the editor output.

Custom merge fields can be added to the editor content by:

* typing the merge field pattern, for example typing `{{myMergeField}}`,
* loading the document data with merge fields that were not specified in the [merge fields definitions](#ckeditor5/latest/features/merge-fields.html--merge-fields-definitions) (including situations where previously existing merge field definition was later removed from the configuration),
* pasting external content that includes text matching the merge field pattern.

Custom merge field will behave like a merge field for which only an id was defined.

<a id="ckeditor5/latest/features/merge-fields.html--document-export-plugins">

#### Document export plugins

You can easily combine merge fields with CKEditor 5’s export features, namely [export to Word](#ckeditor5/latest/features/converters/export-word.html) and [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html). Employing this solution will allow for batch generation of `docx` and `pdf` files and automation (for example automated invitations generation from a client list or personalized envelope labels). Using these output formats will also greatly aid cross-platform interoperability, accessibility and compatibility with various editing solutions, boosting productivity and optimizing the workflow.

Using the [export to Word](#ckeditor5/latest/features/converters/export-word.html) or [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) features for a document with merge fields will produce different results, depending on the current [preview mode](#ckeditor5/latest/features/merge-fields.html--preview-modes). The export features will follow “what you see is what you export” logic.

While export is used in the “labels” preview mode:

* The exported Word document will contain Word document merge fields (it will be exported as a “template” document).
* The exported PDF file will contain merge fields in the default data form `[PREFIX][MERGE_FIELD_ID][SUFFIX]`, for example `{{guestName}}`.
* Image merge fields will not be displayed.

While export is used when default values or data set values are previewed, the merge fields will be replaced by corresponding values, as previewed in the editor. In this case, image merge fields will be preserved.

You can learn more about integrating merge fields with the converter in the dedicated [merge fields integration](#cs/latest/guides/export-to-word/merge-fields.html) guide in the Export to Word documentation.

<a id="ckeditor5/latest/features/merge-fields.html--the-email-feature">

#### The email feature

Merge fields can also be integrated with the [email editing toolset](#ckeditor5/latest/features/email-editing/email.html). Introducing templates and content placeholders allows for highly efficient and automated mail merge. By combining these features, you can easily create precisely targeted newsletters, mailing lists, personalized email messages and other mail merge solutions. This is a great tool not only for e-commerce but also all other business fields.

<a id="ckeditor5/latest/features/merge-fields.html--import-from-word">

#### Import from Word

The [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature will recognize Word document merge fields and will seamlessly convert them to the editor merge fields.

<a id="ckeditor5/latest/features/merge-fields.html--using-merge-fields-with-templates">

#### Using merge fields with templates

Merge fields can be used together with the template feature. Use the “Insert template”  dropdown to add a template into the editor.

<a id="ckeditor5/latest/features/merge-fields.html--common-api">

### Common API

The [MergeFields](../api/module%5Fmerge-fields%5Fmergefields-MergeFields.html) plugin registers:

* The `'insertMergeField'` and `'previewMergeFields'` toolbar and menu bar buttons.
* The `'mergeFieldsData'` option for the [getData()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method (see the [Data output with filled-in merge fields](#ckeditor5/latest/features/merge-fields.html--data-output-with-filled-in-merge-fields) section for the details).

<a id="ckeditor5/latest/features/mermaid.html">source file: "ckeditor5/latest/features/mermaid.html"</a>

## Creating flowcharts and diagrams using Mermaid

You can create flowcharts and diagrams in CKEditor 5 thanks to the experimental integration with the [Mermaid](https://mermaid.js.org/) library. Mermaid uses a Markdown-inspired syntax to create and dynamically modify flowcharts, Gantt diagrams, pie or quadrant charts, graphs, mindmaps, and more.

<a id="ckeditor5/latest/features/mermaid.html--demo">

### Demo

The example below lets you test creating diagrams and flowcharts right during the content creation – no more screenshots that need to be re-created and re-uploaded each time something needs a change!

<a id="ckeditor5/latest/features/mermaid.html--using-mermaid-syntax">

### Using Mermaid syntax

Mermaid offers an extensive and flexible syntax allowing users to create a variety of diagrams, charts, and graphs. Find the complete syntax reference on [Mermaid.js](https://mermaid.js.org/intro/). You can also check out more examples online in [Mermaid Live Editor](https://mermaid.live/).

Learn more about Mermaid syntax and usage in a [dedicated article](https://ckeditor.com/blog/basic-overview-of-creating-flowcharts-using-mermaid/) on our company blog.

<a id="ckeditor5/latest/features/mermaid.html--installation">

### Installation

Please note that this plugin is not imported from the main CKEditor 5 file, but from its own package. 

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration. Please note, that unlike native CKEditor 5 plugins, this one is imported from its own package. Also, that this import is different than the standard CKEditor 5 plugins import:

```
import { ClassicEditor } from 'ckeditor5';
import { Mermaid } from '@ckeditor/ckeditor5-mermaid';

import '@ckeditor/ckeditor5-mermaid/index.css';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Mermaid, /* ... */ ],
        toolbar: [ 'mermaid', /* ... */ ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/minimap.html">source file: "ckeditor5/latest/features/minimap.html"</a>

## Content minimap

The content minimap feature shows a miniature overview of your content. It helps you navigate a document that is too long to fit on the screen.

<a id="ckeditor5/latest/features/minimap.html--demo">

### Demo

Scroll the content, and the minimap in the sidebar will show your current location. To quickly navigate the document, drag the box marking the visible portion of the content. You can also click anywhere on the minimap to move around instantly.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/minimap.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/minimap.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/minimap.html--minimap-container">

#### Minimap container

The container element is essential for the minimap to render. You should pass the reference to the container element in [config.minimap.container](../api/module%5Fminimap%5Fminimapconfig-MinimapConfig.html#member-container). Note that it must have a fixed `width` and `overflow: hidden` when the editor is created:

```
DecoupledEditor
    .create( {
        root: {
            element: document.querySelector( '#editor' )
        },
        // ... Other configuration options ...
        minimap: {
            container: document.querySelector( '.minimap-container' )
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/minimap.html--content-styles-and-classes">

#### Content styles and classes

The minimap feature uses `<iframe>` internally. For a proper look and operation, it is essential for the content (clone) inside the `<iframe>` to have exactly the same styles as the main editor document. If the content of your editor inherits styles from parent containers, you may need to pass the class names of these containers in the feature configuration to maintain style parity. See the [detailed classes documentation](../api/module%5Fminimap%5Fminimapconfig-MinimapConfig.html#member-extraClasses) to learn more.

<a id="ckeditor5/latest/features/minimap.html--demo-configuration">

#### Demo configuration

To configure the editor as [presented above](#ckeditor5/latest/features/minimap.html--demo), you can use the following DOM structure:

```
<div id="document-container">
    <div id="toolbar-container">
        <!-- This is where the document editor toolbar will be inserted. -->
    </div>
    <div class="minimap-wrapper">
        <div class="editor-container">
            <div id="editor-content">
                <!-- This is where the edited content will render (the page). -->
            </div>
        </div>
        <div class="minimap-container">
            <!-- This is where the minimap will be inserted. -->
        </div>
    </div>
</div>

```

Employ the following CSS:

```
.document-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    position: relative;
    flex-grow: 1;
    max-width: 1280px;
    margin: 0 auto;
}

.toolbar-container {
    width: 100%;
}

.minimap-wrapper {
    display: flex;
    flex-direction: row;
    flex-wrap: nowrap;
    max-height: calc( 100vh - 400px );
    width: 100%;
    position: relative;
    top: -1px;
}

.editor-container {
    width: 100%;
    border: 1px solid hsl( 0, 0%, 80% );
    border-right: 0;
    background: hsl( 0, 0%, 95% );
    box-sizing: border-box;
    position: relative;
    overflow: auto;
}

.minimap-container {
    width: 120px;
    flex: 0 0 auto;
    border: 1px solid var(--ck-color-toolbar-border);
    position: relative;
    overflow: hidden;
    max-height: 100%;
}

#editor-content {
    width: calc( 180mm + 2px );
    min-height: calc( 210mm + 2px );
    height: auto;
    padding: 20mm 12mm;
    box-sizing: border-box;
    background: hsl( 0, 0%, 100% );
    border: 1px solid hsl( 0, 0%, 88% );
    box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
    margin: 40px auto;
    overflow: hidden;
}

```

Finally, the JavaScript to run the editor (learn how to [install](#ckeditor5/latest/features/minimap.html--installation) the feature):

```
DecoupledEditor
    .create( {
        root: {
            element: document.querySelector( '#editor-content' )
        },
        // ... Other configuration options ...
        minimap: {
            container: document.querySelector( '.minimap-container' ),
        }
    } )
    .then( editor => {
        const toolbarContainer = document.querySelector( '#toolbar-container' );

        toolbarContainer.appendChild( editor.ui.view.toolbar.element );
    } );

```

<a id="ckeditor5/latest/features/minimap.html--related-features">

### Related features

Here are some other CKEditor 5 features that you can use to navigate content better:

* [Document outline](#ckeditor5/latest/features/document-outline.html) – Display a navigable list of sections (headings) of the document next to the editor.
* [Table of contents](#ckeditor5/latest/features/table-of-contents.html) – Insert a table of contents into the document with a single click.

<a id="ckeditor5/latest/features/minimap.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-minimap>.

<a id="ckeditor5/latest/features/page-break.html">source file: "ckeditor5/latest/features/page-break.html"</a>

## Page break

The page break feature lets you insert page breaks into your content. This gives you more control over the final structure of a document that is printed or [exported to PDF](#ckeditor5/latest/features/converters/export-pdf.html) or [Word](#ckeditor5/latest/features/converters/export-word.html).

<a id="ckeditor5/latest/features/page-break.html--demo">

### Demo

Use the insert page break toolbar button  to see the feature in action. Use the “Open print preview” button below the editor to preview the content.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/page-break.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/page-break.html--related-features">

### Related features

Here are some useful CKEditor 5 features that you can use together with the page break plugin for an all-around paged editing experience:

* The [pagination feature](#ckeditor5/latest/features/pagination/pagination.html) allows you to see where page breaks would be after the document is [exported to PDF](#ckeditor5/latest/features/converters/export-pdf.html) or [to Word](#ckeditor5/latest/features/converters/export-word.html).
* The [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature will allow you to generate editable, paged `.docx` files out of your editor-created content.
* The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature will allow you to generate portable, paged PDF files out of your editor-created content.

<a id="ckeditor5/latest/features/page-break.html--common-api">

### Common API

The [PageBreak](../api/module%5Fpage-break%5Fpagebreak-PageBreak.html) plugin registers:

* the UI button component (`'pageBreak'`),
* the `'pageBreak'` command implemented by [PageBreakCommand](../api/module%5Fpage-break%5Fpagebreakcommand-PageBreakCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Inserts a page break into the selected content.
editor.execute( 'pageBreak' );

```

<a id="ckeditor5/latest/features/page-break.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-page-break>.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html">source file: "ckeditor5/latest/features/pagination/pagination-integration.html"</a>

## Integration with Export to PDF/Word

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--integration-with-export-to-pdfword">

### Integration with Export to PDF/Word

This guide is meant as a point of reference for anyone integrating the `[Pagination](#ckeditor5/latest/features/pagination/pagination.html)`, `[Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html)`, and `[Export to Word](#ckeditor5/latest/features/converters/export-word.html)` features together. It describes the whole process from creating a custom editor and configuring it to having a working solution.

We strongly advise you to get familiar with all three mentioned plugins’ user guides before reading this guide.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--using-ckeditor-5-builder">

### Using CKEditor 5 Builder

If you do not wish to go through this tutorial, and just want to get a working editor, we recommend using our [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs). It offers a set of editor presets, a catalog of editor features to choose from, and many more useful options.

Choose the Document Editor preset to get the exports and pagination features. CKEditor 5 Builder will provide the necessary HTML, CSS, and JavaScript files for your editor setup.

If you want to get a better understanding of this setup, read the tutorial below.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--before-you-start">

### Before you start

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

For the export plugins, you will need a special [token endpoint](https://ckeditor.com/docs/cs/latest/guides/security/token-endpoint.html). To get it, log into your CKEditor Ecosystem Dashboard account and [follow the guide on creating a token URL](https://ckeditor.com/docs/trial/latest/guides/export-to-pdf/quick-start.html#account-dashboard). If the export features are used without this token, all generated documents will contain a watermark at the bottom of every page.

After obtaining all the credentials needed, create a custom editor and configure it.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--lets-start">

### Let’s start!

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/pagination-and-exports/starter-files pagination-and-exports
cd pagination-and-exports

npm install
npm run dev

```

This will create a new directory called `pagination-and-exports` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

Open the URL displayed in your terminal. If everything goes well, you will see an initial text on the screen and errors in the console. It is expected, and we will fix it in the following steps.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--adding-licenses">

#### Adding licenses

You need to provide a license key for the pagination feature as well as the Cloud Services configuration for the export plugins (which you obtained in [step one](#ckeditor5/latest/features/pagination/pagination-integration.html--activating-the-feature)).

Go to the `src/main.js`, and fill the required configuration.

```
// More editor's configuration.
// ...
cloudServices: {
    // Provide a correct value here. You can find it in the CKEditor Ecosystem Dashboard:
    // https://dashboard.ckeditor.com/login
    tokenUrl: 'https://example.com/cs-token-endpoint'
},
licenseKey: '<YOUR_LICENSE_KEY>',
// More editor's configuration.
// ...

```

After adding those values, the editor should allow writing in it, but the browser’s console will inform us about the missing configuration.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--adding-plugins-configuration">

#### Adding plugins’ configuration

The pagination configuration has to be in sync with the configuration of the export plugins. All three configurations need to have the same margin values and page format set. This is due to the handling of default editor styles. In this guide, you will use the A4 format, but you can use other paper sizes as well.

Open again the `src/main.js`, and add additional configuration:

```
// More editor's configuration.
// ...
pagination: {
    // Page width and height reflect the A4 format.
    pageWidth: '21cm',
    pageHeight: '29.7cm',

    pageMargins: {
        top: '20mm',
        bottom: '20mm',
        right: '12mm',
        left: '12mm'
    }
},
exportPdf: {
    fileName: 'my-sample-file.pdf',
    converterOptions: {
        document: {
            size: 'A4',
            orientation: 'portrait',
            margins: {
                top: '20mm',
                bottom: '20mm',
                right: '12mm',
                left: '12mm'
            }
        }
    }
},
exportWord: {
    fileName: 'my-sample-file.docx',
    converterOptions: {
       document: {
            size: 'A4',
            margin: {
                top: '20mm',
                bottom: '20mm',
                right: '12mm',
                left: '12mm'
            }
        }
    }
},

```

After adding the configuration, the exports work but we still need to work on the styles.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--styling-the-editor">

#### Styling the editor

When using the [decoupled editor (document editor)](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html), you need to make sure that the editor styles match precisely the configuration options that you provided to the feature and the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html--configuration) or [export to Word](#ckeditor5/latest/features/converters/export-word.html--configuration) features. Additionally, you just want the editor to look good.

To address this issue, open the `style.css` file, and add the following declarations:

```
/* Editor styles */
.document-container {
    width: 1000px;
    margin: auto;
    background-color: rgb(238, 238, 238);
}
.editor-container {
    border: 1px solid hsl( 0, 0%, 80% );
    max-height: calc( 100vh - 100px );
    overflow: auto;
}
.ck.ck-editor__editable_inline {
    /*
        A4 size.
        Expand the width by 2px because of the border and "box-sizing: border-box".
    */
    width: calc( 210mm + 2px );
    height: auto;
    padding: 20mm 12mm;
    box-sizing: border-box;
    border: 1px solid hsl( 0, 0%, 88% );
    background: hsl( 0, 0%, 100% );
    box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
    margin: 40px auto;
}

```

Our `main.js` already imports `style.js`, so after saving the CSS file, you should see a nicely styled editor in your browser.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--styling-the-content">

#### Styling the content

Try to add a block quote, and export the content to a PDF. It works, but the content in the file looks different.

Our `main.js` imports the styles of CKEditor 5\. Apart from styling the editor’s editable element, they also have styles that control how the content inside the editor looks. When using the pagination feature together with export to PDF and export to Word, you need to make sure that these styles are sent to the converters. This means they will be actually applied to the content when generating the document. They should also not create a discrepancy between the pagination lines in the editor and page breaks in the generated document.

```
// More editor's configuration.
// ...
exportPdf: {
    stylesheets: [
        // We will add links to stylesheets here.
    ],
    // More configuration of the Export to PDF.
    // ...
},
exportWord: {
    stylesheets: [
        // We will add links to stylesheets here.
    ],
    // More configuration of the export to Word.
    // ...
}
// More editor's configuration.
// ...

```

Before we add a proper configuration, let’s add a few new declarations that are specific to the pagination plugin, and also adjust the line height. Add them to `style.css`:

```
/* Content styles */
@media print {
    body {
        margin: 0 !important;
    }
}
.ck-content * {
    line-height: 1.5;
}
.ck-content .table thead {
    display: table-row-group;
}
.ck-content .table tr {
    break-inside: avoid;
    break-after: auto;
}

```

There are several strategies how to pass style sheets in the configuration. We could add relative paths or links to them. Let’s use the simplest strategy in this tutorial, but keep in mind that your bundler or framework may offer a different solutions.

Create a `public` folder in the root of the project, and copy all the style sheets that we use there.

```
mkdir public
cp node_modules/ckeditor5/dist/index.css public/ckeditor5.css
cp node_modules/ckeditor5-premium-features/dist/index.css public/ckeditor5-premium-features.css
cp src/style.css public

```

Then add the following configuration to the exports:

```
// More editor's configuration.
// ...
exportPdf: {
    stylesheets: [
        './ckeditor5.css',
        './ckeditor5-premium-features.css',
        './style.css'
    ],
    // More configuration of the Export to PDF.
    // ...
},
exportWord: {
    stylesheets: [
        './ckeditor5.css',
        './ckeditor5-premium-features.css',
        './style.css'
    ],
    // More configuration of the export to Word.
    // ...
}
// More editor's configuration.
// ...

```

You can read more about sending styles to the server in the [troubleshooting section](#ckeditor5/latest/features/pagination/pagination.html--troubleshooting) of Pagination overview.

This is it, we have a working pagination integration with Export to Word and Export to PDF!

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--demo">

#### Demo

The editor below has the [Pagination](#ckeditor5/latest/features/pagination/pagination.html), [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) and [Export to Word](#ckeditor5/latest/features/converters/export-word.html) features enabled. Keep in mind that this demo may slightly differ from the editor you have just built. This is because of fonts and styles specific to this documentation page.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--final-solution">

### Final solution

There is a repository available with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/pagination-and-exports/final-project) that you can download and play with. Remember to fill in the required license and `tokenUrl` information.

<a id="ckeditor5/latest/features/pagination/pagination-integration.html--troubleshooting">

#### Troubleshooting

Please keep in mind that each of the plugins used in this guide has some known issues – this could be partial or missing support for other CKEditor 5 plugins, partial browser support, some known bugs, etc. When combined, these sometimes might cause problems for certain more complicated use cases. We strongly advise you to go through all _Known issues_ sections in the features’ respective documentation pages and make sure that you understand all their limitations.

If you would like to report a bug or propose enhancements for these plugins, we encourage you to use the [CKEditor 5 issue tracker](https://github.com/ckeditor/ckeditor5/issues). If you would like to use CKEditor 5 as a part of a commercial solution or have a request for custom development, feel free to contact us through our [support channel](https://ckeditor.com/contact/) \- our team will make sure to answer all your questions.

<a id="ckeditor5/latest/features/pagination/pagination.html">source file: "ckeditor5/latest/features/pagination/pagination.html"</a>

## Pagination overview

The pagination feature is a dedicated [decoupled editor](#ckeditor5/latest/examples/builds/document-editor.html) plugin that lets you see where page breaks will be after the document is [exported to PDF](#ckeditor5/latest/features/converters/export-pdf.html). The feature respects page breaks inserted by the user with the [page break feature](#ckeditor5/latest/features/page-break.html).

<a id="ckeditor5/latest/features/pagination/pagination.html--demo">

### Demo

The demo below lets you see page break lines. They show you the location of page breaks in an exported PDF or DOCX file. Use the pagination feature toolbar buttons to navigate back  and forth  between pages.

<a id="ckeditor5/latest/features/pagination/pagination.html--additional-feature-information">

### Additional feature information

In addition to page breaks, the pagination feature shows you page numbers and the total number of pages in the document. The feature also introduces a dedicated toolbar that lets you easily go to the next or previous page of the document or jump straight to a particular page.

The pagination feature is complementary to the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) and [export to Word](#ckeditor5/latest/features/converters/export-word.html) features of CKEditor 5, ensuring the proper output every time. Combined with other CKEditor 5 features, these plugins allow for advanced editing and document creation implementations. This kind of practical application is shown in the [How to create ready-to-print documents with CKEditor 5 pagination feature](https://ckeditor.com/blog/How-to-create-ready-to-print-documents-with-page-structure-in-WYSIWYG-editor---CKEditor-5-pagination-feature/) blog post.

The pagination plugin cannot be used to reflect the original page division in content [imported from Word](#ckeditor5/latest/features/converters/import-word/import-word.html). This is an export-only feature.

<a id="ckeditor5/latest/features/pagination/pagination.html--before-you-start">

### Before you start

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

For the export plugins, you will need a special [token endpoint](https://ckeditor.com/docs/cs/latest/guides/security/token-endpoint.html). To get it, log into your CKEditor Ecosystem Dashboard account and [follow the guide on creating a token URL](https://ckeditor.com/docs/trial/latest/guides/export-to-pdf/quick-start.html#account-dashboard). When export features are used without this token, all generated documents will contain a watermark at the bottom of every page.

After obtaining all the credentials needed, create a custom editor and configure it.

<a id="ckeditor5/latest/features/pagination/pagination.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/pagination/pagination.html--configuration">

### Configuration

The configuration is crucial for allowing the pagination feature to measure where the page breaks would be. These configuration values must match the [export to PDF](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdfConfig.html) or the [export to Word](../../api/module%5Fexport-word%5Fexportword-ExportWordConfig.html) configuration. The structure of both configurations is different.

<a id="ckeditor5/latest/features/pagination/pagination.html--example-configuration">

#### Example configuration

```
{
    pagination: {
        // A4
        pageWidth: '21cm',
        pageHeight: '29.7cm',

        pageMargins: {
            top: '20mm',
            bottom: '20mm',
            left: '12mm',
            right: '12mm'
        }
    }
}

```

<a id="ckeditor5/latest/features/pagination/pagination.html--plugin-options">

#### Plugin options

The plugin options tell the pagination feature what the format of the page and the page margins are. There is also an additional configuration option that allows you to enable pagination in all browsers, including the officially unsupported ones.

* **[config.pagination.pageWidth](../../api/module%5Fpagination%5Fpagination-PaginationConfig.html#member-pageWidth)**, **[config.pagination.pageHeight](../../api/module%5Fpagination%5Fpagination-PaginationConfig.html#member-pageHeight)**  
The page dimensions.
* **[config.pagination.pageMargins](../../api/module%5Fpagination%5Fpagination-PaginationConfig.html#member-pageMargins)**  
The page margins.
* **[config.pagination.enableOnUnsupportedBrowsers](../../api/module%5Fpagination%5Fpagination-PaginationConfig.html#member-enableOnUnsupportedBrowsers)**  
The pagination feature is by default enabled only in browsers that are using the Blink engine (Chrome, Chromium, newer Edge, newer Opera). This behavior can be modified by setting this configuration option to `true`.

<a id="ckeditor5/latest/features/pagination/pagination.html--pagination-toolbar">

#### Pagination toolbar

CKEditor 5 pagination feature provides a few toolbar items that can be added to your editor toolbar configuration. They are all optional – the pagination feature does not need them to show you the document page division.

The pagination toolbar buttons make the document navigation easier, though:

* The `'nextPage'` button allows you to go to the next document page.
* The `'previousPage'` button allows you to go to the previous document page.
* The `'pageNavigation'` toolbar item shows you the total page count and allows you to go straight to a particular page number.

```
DecoupledEditor
    .create( {
        root: {
            element: document.querySelector( '#editor' ),
        },
        // ... Other configuration options ...
        toolbar: [
            'previousPage',
            'nextPage',
            'pageNavigation',
            '|',
            // More toolbar items.
            // ...
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/pagination/pagination.html--troubleshooting">

### Troubleshooting

The pagination feature computes where the page breaks would be in the local browser, but the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) or [export to Word](#ckeditor5/latest/features/converters/export-word.html) features are handled by dedicated HTML to PDF and DOCX converter services of CKEditor Cloud Services. Because of this, it is important to match the content styles with those sent to the backend service. Even a minor difference in the margin, padding, font size, etc. setting may lead to inconsistencies between the content in the editor and the generated PDF or Word file. Because of this, the local browser could calculate page breaks in incorrect places.

<a id="ckeditor5/latest/features/pagination/pagination.html--editor-content-styling">

#### Editor content styling

For example, if you are using [decoupled editor (document editor)](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html), you need to make sure that the editor styles match precisely the configuration options that you provided to the feature and to the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) or [export to Word](#ckeditor5/latest/features/converters/export-word.html) features.

```
.ck.ck-editor__editable_inline {
    /* A4 size */
    width: calc( 210mm + 2px ); /* Expand the width by 2px because of the border and "box-sizing: border-box". */
    height: auto;
    padding: 20mm 12mm;
    box-sizing: border-box;

    border: 1px solid hsl( 0, 0%, 88% );
    background: hsl( 0, 0%, 100% );
    box-shadow: 0 2px 8px hsla( 0, 0%, 0%, .08 );
    margin: 40px auto;
    overflow: hidden;
}

```

Note the calculation of the width of the element.

<a id="ckeditor5/latest/features/pagination/pagination.html--the-style-sheets-sent-to-the-service">

#### The style sheets sent to the service

While preparing the style sheets to send to the export to PDF or export to Word service, you should:

* Make sure that the styling of all elements is exact.
* Reset the default page margins:  
```  
@media print {  
    body {  
        margin: 0 !important;  
    }  
}  
```
* Override the default browser behavior of breaking the tables:  
```  
.ck-content .table thead {  
    display: table-row-group;  
}  
.ck-content .table tr {  
    break-inside: avoid;  
    break-after: auto;  
}  
```

<a id="ckeditor5/latest/features/pagination/pagination.html--ckeditor-5-initialization">

#### CKEditor 5 initialization

If you want to create the editor detached and attach it to the DOM tree later, remember to call `editor.ui.update();` after the editor is attached.

```
DecoupledEditor
    .create( {
        ...config,
        root: {
            initialData
        }
    } )
    .then( editor => {
        const editorContainer = document.querySelector( '#editor-container' );
        const toolbarContainer = document.querySelector( '#toolbar-container' );

        toolbarContainer.appendChild( editor.ui.view.toolbar.element );
        editorContainer.appendChild( editor.ui.view.editable.element );

        editor.ui.update();
    } );

```

<a id="ckeditor5/latest/features/pagination/pagination.html--known-issues">

### Known issues

<a id="ckeditor5/latest/features/pagination/pagination.html--table-captions-causing-inconsistent-pagination">

#### Table captions causing inconsistent pagination

Table captions may occasionally break pagination calculations when a page break falls inside a table that has a caption. This is a known bug in browsers and, until it is fixed, you must use the workaround — use a native `table`/`caption` element instead of `figure`/`figcaption`. Enable the workaround by setting:

```
editor.config.set( 'table.tableCaption.useCaptionElement', true );

```

<a id="ckeditor5/latest/features/pagination/pagination.html--automatic-page-breaks-in-export-to-word">

#### Automatic page breaks in Export to Word

Browser engines and Microsoft Word differ significantly. Because of that, the automatic prediction of page breaks in [Export to Word](#ckeditor5/latest/features/converters/export-word.html--how-it-works) is problematic and error-prone. Therefore, pagination in the Export to Word should be based solely on [page breaks](#ckeditor5/latest/features/page-break.html). We strongly recommend reviewing your document’s structure before exporting and manually applying the page breaks to maintain the preferred structure. You can also use [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html), where predicting page breaks is more straightforward and works more consistently.

<a id="ckeditor5/latest/features/pagination/pagination.html--unsupported-plugins">

#### Unsupported plugins

Not all CKEditor 5 plugins and features are compatible with pagination and export to PDF or Word at the moment. Refer to the documentation of the export features to learn more:

* [Export to PDF – known issues](#ckeditor5/latest/features/converters/export-pdf.html--known-issues)
* [Export to Word – known issues](#ckeditor5/latest/features/converters/export-word.html--known-issues)
* [Document title](#ckeditor5/latest/features/title.html) – cause conflicts

<a id="ckeditor5/latest/features/pagination/pagination.html--browser-compatibility">

#### Browser compatibility

Currently, the pagination feature works best with the following web browsers:

* Chrome
* Chromium
* latest Edge
* latest Opera

The pagination plugin does not work in Firefox yet. There are also some glitches in Safari. To prevent users from seeing potentially invalid pagination, the plugin disables itself after detecting these unsupported browsers.

If you want to enable the pagination feature in an unsupported browser, you can set the [config.pagination.enableOnUnsupportedBrowsers](../../api/module%5Fpagination%5Fpagination-PaginationConfig.html#member-enableOnUnsupportedBrowsers) configuration option to `true` or enable it at runtime by calling `editor.plugins.get( 'Pagination' ).clearForceDisabled( 'browserCheck' )`.

<a id="ckeditor5/latest/features/pagination/pagination.html--related-features">

### Related features

Here are some useful CKEditor 5 features that you can use together with the pagination plugin for an all-around paged editing experience:

* The [page break feature](#ckeditor5/latest/features/page-break.html) allows you to manually insert a page break into your document.
* The [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature will allow you to generate editable `.docx` files out of your editor-created content.
* The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature will allow you to generate portable PDF files out of your editor-created content.

<a id="ckeditor5/latest/features/pagination/pagination.html--common-api">

### Common API

The [Pagination](../../api/module%5Fpagination%5Fpagination-Pagination.html) plugin registers:

* The `'pageNavigation'` toolbar item.
* The `'nextPage'` and `'previousPage'` buttons.
* The `'pagination'` option for the [getData()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method:  
```  
const data = editor.getData( { pagination: true } );  
```  
This option enables downcast conversion of the calculated page breaks.

  * At the beginning of the element:  
  ```  
  <p style="page-break-before:always;" data-pagination-page="4"> ... </p>  
  ```
  * Inside the text:  
  ```  
  <p> ... <span style="page-break-before:always;" data-pagination-page="8"></span> ... </p>  
  ```

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html">source file: "ckeditor5/latest/features/pasting/paste-from-google-docs.html"</a>

## Pasting content from Google Docs

The paste from Google Docs feature lets you paste content from Google Docs and preserve its original structure and formatting.

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--demo">

### Demo

To test pasting from Google Docs, open the [sample Google Docs document](https://docs.google.com/document/d/1pjLA5P0SKVtimJSiCgtMjHrmZWCB3TqqgpFdRoCS9gU/edit). Then copy its content and paste it into the editor below.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--additional-feature-information">

### Additional feature information

Thanks to the paste from Google Docs feature, you can copy and paste a Google Docs document into CKEditor 5 and maintain basic text styling, heading levels, links, lists, tables, and images.

When the plugin is enabled, it automatically detects Google Docs content and transforms its structure and formatting to clean HTML which is then transformed into semantic content by the editor.

The [PasteFromOffice](../../api/module%5Fpaste-from-office%5Fpastefromoffice-PasteFromOffice.html) plugin also allows you to paste content from Microsoft Word. See the [pasting content from Microsoft Office](#ckeditor5/latest/features/pasting/paste-from-office.html) guide to learn more.

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--automatic-content-filtering">

### Automatic content filtering

With CKEditor 5 you do not need to worry about pasting messy content from Google Docs (or any other possible sources). Thanks to the CKEditor 5 [custom data model](#ckeditor5/latest/framework/index.html), only content that is specifically handled by the loaded rich-text editor features will be preserved.

This means that if you did not enable, for instance, [font family and font size](#ckeditor5/latest/features/font.html) features, this sort of formatting will be automatically stripped off when you paste content from Google Docs and other sources (like other websites).

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--support-for-other-applications">

### Support for other applications

At the current stage, the focus of the `@ckeditor/ckeditor5-paste-from-office` package is on supporting content that comes from [Microsoft Word](#ckeditor5/latest/features/pasting/paste-from-office.html) and Google Docs. However, it does not mean that pasting from other similar applications (such as Microsoft Excel) is not supported.

By default, CKEditor 5 will support pasting rich-text content from these applications, however, some styles and formatting may be lost, depending on the source application. Also, other minor bugs may appear.

You can find more information regarding compatibility with other applications in [this ticket](https://github.com/ckeditor/ckeditor5/issues/1184#issuecomment-409828069).

If you think that support for any of the applications needs improvements, add 👍 and comments in the following issues:

* [Support pasting from Excel](https://github.com/ckeditor/ckeditor5/issues/2513).
* [Support pasting from Libre Office](https://github.com/ckeditor/ckeditor5/issues/2520).
* [Support pasting from Pages](https://github.com/ckeditor/ckeditor5/issues/2527).

Feel free to open a [new feature request](https://github.com/ckeditor/ckeditor5/issues/new/choose) for other similar applications, too!

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--related-features">

### Related features

CKEditor 5 supports a wider range of paste features, including:

* [Paste plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html) – Paste text without formatting that will inherit the style of the content it was pasted into.
* [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) – Paste content from Microsoft Word and keep the original structure and formatting.
* [Enhanced paste from Office](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) – Enhanced paste from Office is a premium version of the plugin that offers far greater capabilities.
* [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) – Convert Word files directly into HTML content.
* [Paste Markdown](#ckeditor5/latest/features/pasting/paste-markdown.html) – Paste Markdown-formatted content straight into the editor.

<a id="ckeditor5/latest/features/pasting/paste-from-google-docs.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-paste-from-office>.

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html">source file: "ckeditor5/latest/features/pasting/paste-from-office-enhanced.html"</a>

## Enhanced paste from Office

Paste from Office features let you paste content from Microsoft Word and Microsoft Excel and preserve its original structure and formatting. This is an advanced, premium enhanced paste from Office feature.

There is also the [basic, open-source Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) feature, You can read more about the differences between these two [further in this guide](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--content-formatting-support).

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--demo">

### Demo

Use these sample documents to test pasting from Microsoft Office:

* [Sample Word document](../../assets/PasteFromOfficeEnhancedWordSample.docx)
* [Sample Excel spreadsheet](../../assets/PasteFromOfficeEnhancedExcelSample.xlsx)

To test pasting from Office, download the sample documents and open them in Microsoft Office applications. Then, copy the content and paste it into the editor below.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--content-formatting-support">

### Content formatting support

Enhanced paste from Office retains rich content pasted from Microsoft Office applications. See below the full table of supported styles and formatting.

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--microsoft-word">

#### Microsoft Word

**Note:** The name of each group in the table corresponds to the category in Word’s “Modify style” user interface. If a specific formatting is supported natively (without using the [General HTML Support](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--installation) feature), a plugin name responsible for the formatting is provided in parentheses.

| Group                                  | Formatting                                                                                                    | Paste from Office                                                                                                                                                           | Premium feature Enhanced paste from Office                                                                                                                          |                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Native support                         | With [General HTML Support](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--installation) |                                                                                                                                                                             |                                                                                                                                                                     |                                                                                               |
| Font                                   | Font family                                                                                                   | ✅ Yes                                                                                                                                                                       | ✅ Yes ([FontFamily](#ckeditor5/latest/features/font.html))                                                                                                          | ✅ Yes                                                                                         |
| Font style (weight, italic)            | ✅ Yes                                                                                                         | ✅ Yes ([Bold](#ckeditor5/latest/features/basic-styles.html), [Italic](#ckeditor5/latest/features/basic-styles.html))                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Font size                              | ✅ Yes                                                                                                         | ✅ Yes ([FontSize](#ckeditor5/latest/features/font.html))                                                                                                                    | ✅ Yes                                                                                                                                                               |                                                                                               |
| Text color                             | ✅ Yes                                                                                                         | ✅ Yes ([FontColor](#ckeditor5/latest/features/font.html))                                                                                                                   | ✅ Yes                                                                                                                                                               |                                                                                               |
| Underline                              | ✅ Yes                                                                                                         | ✅ Yes ([Underline](#ckeditor5/latest/features/basic-styles.html)) [\[1\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-underline-color)    | ✅ Yes [\[1\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-underline-color)                                                        |                                                                                               |
| Advanced underline                     | ❌ No                                                                                                          | ✅ Yes ([Underline](#ckeditor5/latest/features/basic-styles.html)) [\[2\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-underline-advanced) | ✅ Yes [\[2\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-underline-advanced)                                                     |                                                                                               |
| Emphasis mark                          | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Strikethrough                          | ✅ Yes                                                                                                         | ✅ Yes ([Strikethrough](#ckeditor5/latest/features/basic-styles.html))                                                                                                       | ✅ Yes                                                                                                                                                               |                                                                                               |
| Double strikethrough                   | ❌ No                                                                                                          | ✅ Yes ([Strikethrough](#ckeditor5/latest/features/basic-styles.html)) [\[3\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-strike)         | ✅ Yes ([Strikethrough](#ckeditor5/latest/features/basic-styles.html)) [\[3\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-font-strike) |                                                                                               |
| Superscript                            | ✅ Yes                                                                                                         | ✅ Yes ([Superscript](#ckeditor5/latest/features/basic-styles.html))                                                                                                         | ✅ Yes                                                                                                                                                               |                                                                                               |
| Subscript                              | ✅ Yes                                                                                                         | ✅ Yes ([Subscript](#ckeditor5/latest/features/basic-styles.html))                                                                                                           | ✅ Yes                                                                                                                                                               |                                                                                               |
| Small caps                             | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| All caps                               | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Hidden                                 | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Character scale                        | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Character spacings                     | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Advanced typography                    | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Paragraph                              | Alignment                                                                                                     | ✅ Yes                                                                                                                                                                       | ✅ Yes ([Alignment](#ckeditor5/latest/features/text-alignment.html))                                                                                                 | ✅ Yes                                                                                         |
| Indentation left                       | ✅ Yes                                                                                                         | ✅ Yes ([IndentBlock](#ckeditor5/latest/features/indent.html))                                                                                                               | ✅ Yes                                                                                                                                                               |                                                                                               |
| Indentation right                      | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Spacing before                         | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Spacing after                          | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Line spacing                           | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Line spacing at                        | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| No space between same–style paragraphs | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Tabs                                   | Alignment                                                                                                     | ❌ No                                                                                                                                                                        | ✅ Yes [\[4\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-tabs)                                                                        | ✅ Yes [\[4\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-tabs)  |
| Leader                                 | ❌ No                                                                                                          | ✅ Yes [\[4\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-tabs)                                                                                | ✅ Yes [\[4\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-tabs)                                                                        |                                                                                               |
| Borders and shading                    | Style                                                                                                         | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                | ✅ Yes                                                                                         |
| Color                                  | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Width                                  | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Side                                   | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| From text                              | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Fill                                   | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Pattern style                          | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes [\[5\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-borders-and-shading-pattern-style)                                           |                                                                                               |
| Pattern color                          | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ✅ Yes                                                                                                                                                               |                                                                                               |
| Language                               | Language                                                                                                      | ❌ No                                                                                                                                                                        | ✅ Yes ([TextPartLanguage](#ckeditor5/latest/features/language.html))                                                                                                | ✅ Yes                                                                                         |
| Do not check spelling                  | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Frame                                  | Text wrapping                                                                                                 | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                | ❌ No                                                                                          |
| Size                                   | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Horizontal                             | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Vertical                               | ❌ No                                                                                                          | ❌ No                                                                                                                                                                        | ❌ No                                                                                                                                                                |                                                                                               |
| Bullet points and Numbering            | General                                                                                                       | ✅ Yes ([List](#ckeditor5/latest/features/lists/lists.html)) [\[7\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-lists)                         | ✅ Yes ([List](#ckeditor5/latest/features/lists/lists.html)) [\[7\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-lists)                 | ✅ Yes [\[7\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--word-lists) |

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--microsoft-excel">

#### Microsoft Excel

**Note:** The name of each group in the table corresponds to the category in the Excel “Format cells” user interface. If a specific formatting is supported natively (without using the [General HTML Support](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--installation) feature), a plugin name responsible for the formatting is provided in parentheses.

| Group                            | Formatting                                                                                                    | Paste from Office                                                                                                                                                                  | Premium feature Enhanced paste from Office                                                                  |       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----- |
| Native support                   | With [General HTML Support](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--installation) |                                                                                                                                                                                    |                                                                                                             |       |
| Alignment                        | Horizontal alignment                                                                                          | ❌ No                                                                                                                                                                               | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                | ✅ Yes |
| Vertical alignment               | ❌ No                                                                                                          | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                                                                                       | ✅ Yes                                                                                                       |       |
| Indent                           | ❌ No                                                                                                          | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                                                                                       | ✅ Yes                                                                                                       |       |
| Orientation (angle)              | ❌ No                                                                                                          | ❌ No                                                                                                                                                                               | ❌ No                                                                                                        |       |
| Font                             | Family                                                                                                        | ❌ No                                                                                                                                                                               | ✅ Yes ([FontFamily](#ckeditor5/latest/features/font.html))                                                  | ✅ Yes |
| Style                            | ❌ No                                                                                                          | ✅ Yes ([Bold](#ckeditor5/latest/features/basic-styles.html), [Italic](#ckeditor5/latest/features/basic-styles.html))                                                               | ✅ Yes                                                                                                       |       |
| Size                             | ❌ No                                                                                                          | ✅ Yes ([FontSize](#ckeditor5/latest/features/font.html))                                                                                                                           | ✅ Yes                                                                                                       |       |
| Underline                        | ❌ No                                                                                                          | ✅ Yes ([Underline](#ckeditor5/latest/features/basic-styles.html))                                                                                                                  | ✅ Yes                                                                                                       |       |
| Advanced underline (like double) | ❌ No                                                                                                          | ❌ No                                                                                                                                                                               | ❌ No                                                                                                        |       |
| Color                            | ❌ No                                                                                                          | ✅ Yes ([FontColor](#ckeditor5/latest/features/font.html))                                                                                                                          | ✅ Yes                                                                                                       |       |
| Strikethrough                    | ❌ No                                                                                                          | ✅ Yes ([Strikethrough](#ckeditor5/latest/features/basic-styles.html))                                                                                                              | ✅ Yes                                                                                                       |       |
| Superscript                      | ❌ No                                                                                                          | ✅ Yes ([Superscript](#ckeditor5/latest/features/basic-styles.html))                                                                                                                | ✅ Yes                                                                                                       |       |
| Subscript                        | ❌ No                                                                                                          | ✅ Yes ([Subscript](#ckeditor5/latest/features/basic-styles.html))                                                                                                                  | ✅ Yes                                                                                                       |       |
| Border                           | Border color                                                                                                  | ❌ No                                                                                                                                                                               | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                | ✅ Yes |
| Border width                     | ❌ No                                                                                                          | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                                                                                       | ✅ Yes                                                                                                       |       |
| Border style                     | ❌ No                                                                                                          | ✅ Yes [\[1\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--excel-border-style)                                                                              | ✅ Yes [\[1\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--excel-border-style)       |       |
| Borders across cell (diagonal)   | ❌ No                                                                                                          | ❌ No                                                                                                                                                                               | ❌ No                                                                                                        |       |
| Fill                             | Background                                                                                                    | ❌ No                                                                                                                                                                               | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html))                                | ✅ Yes |
| Pattern color                    | ❌ No                                                                                                          | ✅ Yes ([TableCellProperties](#ckeditor5/latest/features/tables/tables.html)) [\[2\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--excel-fill-pattern-color) | ✅ Yes [\[2\]](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--excel-fill-pattern-color) |       |
| Pattern style                    | ❌ No                                                                                                          | ❌ No                                                                                                                                                                               | ❌ No                                                                                                        |       |

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--support-for-other-office-applications">

### Support for other office applications

At the current stage, the focus of `@ckeditor/ckeditor5-paste-from-office` and `@ckeditor/ckeditor5-paste-from-office-enhanced` packages is on supporting content that comes from Microsoft Word, Microsoft Excel, and [Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html). However, it does not mean that pasting from other similar applications (such as Microsoft PowerPoint) is not supported.

By default, CKEditor 5 will support pasting rich-text content from these applications, however, some styles and formatting may be lost, depending on the source application. Also, other minor bugs may appear.

You can find more information about compatibility with other applications in [this ticket](https://github.com/ckeditor/ckeditor5/issues/1184#issuecomment-409828069).

If you think that support for any of the applications needs improvements, add 👍 and comments in the following issues:

* [Support pasting from Libre Office](https://github.com/ckeditor/ckeditor5/issues/2520).
* [Support pasting from Pages](https://github.com/ckeditor/ckeditor5/issues/2527).

Feel free to open a [new feature request](https://github.com/ckeditor/ckeditor5/issues/new/choose) for other similar applications, too!

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--installation">

### Installation

To add the enhanced paste from Office feature to your editor, you need to install [basic, open-source paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html), enhanced paste from Office and [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) plugins. The `GeneralHtmlSupport` plugin is optional but recommended for optimal retention and accuracy of pasted styles. [Learn more](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--configuration).

We highly recommend you also add other editor packages to get as much native support for pasted content as possible. You can learn more about editor features that work out–of–the–box with content pasted from Microsoft Office in a [dedicated section](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--content-formatting-support). To install the recommended packages, execute the following command:

Add the `PasteFromOffice`, `PasteFromOfficeEnhanced`, and `GeneralHtmlSupport` plugins to your plugin list as well as other editor features that support content pasted from Microsoft Office (`Bold`, `Italic`, `FontColor`, `Indent`, etc.):

Finally, [update the configuration](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--configuration).

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--activating-the-feature">

### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--configuration">

### Configuration

Enhanced paste from Office does not come with its own configuration. Still, we highly recommend to load and configure other editor features in a certain way for optimal retention and performance of pasted styles:

* [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) – Enabling and [configuring](#ckeditor5/latest/features/html/general-html-support.html--enabling-all-html-features) this feature will allow you to make the most of the enhanced paste from Office by retaining advanced formatting that would otherwise be rejected by core editor features. See the [content compatibility table](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--content-formatting-support) to learn more.
* [Font size and family](#ckeditor5/latest/features/font.html) – Loading and configuring these features will ensure maximal compatibility of fonts in the pasted content.

The recommended configuration is as follows:

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--known-issues">

### Known issues

* There is a known issue with cell widths being incorrect upon pasting from Microsoft Excel. [Learn more](https://github.com/ckeditor/ckeditor5/issues/14521).
* Headings pasted from Microsoft Word with a normal font weight configured in styles will be rendered using a bold font due to the default style sheets provided by the editor.
* A bold text pasted from Microsoft Excel may be occasionally displayed as normal for specific font faces.
* There is a known issue with font family, font size, and text part language values being displayed incorrectly in the CKEditor UI.

<a id="ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--related-features">

### Related features

CKEditor 5 supports a wider range of paste features, including:

* [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) – Basic, open-source version of the paste from Office plugin.
* [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) – Paste content from Google Docs, maintaining the original formatting and structure.
* [Paste plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html) – Paste text without formatting that will inherit the style of the content it was pasted into.
* [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) – Convert Word files directly into HTML content. You can read more about the differences between the paste from Office and import from Word features in the [dedicated comparison guide](#ckeditor5/latest/features/converters/import-word/features-comparison.html).

<a id="ckeditor5/latest/features/pasting/paste-from-office.html">source file: "ckeditor5/latest/features/pasting/paste-from-office.html"</a>

## Paste from Office

Paste from Office features let you paste content from Microsoft Word and Microsoft Excel and preserve its original structure and formatting. This is the basic, open-source Paste from Office feature. You can also try the more advanced, premium [enhanced Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) feature.

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--demo">

### Demo

Use these sample documents to test pasting from Microsoft Office Word and Excel:

* [Sample Word document](../../assets/PasteFromOfficeEnhancedWordSample.docx)
* [Sample Excel spreadsheet](../../assets/PasteFromOfficeEnhancedExcelSample.xlsx)

To test pasting from Office, download the sample documents and open them in Microsoft Office applications. Then, copy the content and paste it into the editor below.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--enhanced-paste-from-office">

### Enhanced paste from Office

Refer to the [enhanced Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html--content-formatting-support) guide for a full comparison of supported styles and formatting between the basic and premium versions.

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--additional-feature-information">

### Additional feature information

Thanks to the paste from Office feature, you can copy and paste Microsoft Word documents into CKEditor 5 and maintain basic text styling, heading levels, links, lists, tables, and images.

When the plugin is enabled, it automatically detects Microsoft Word content and transforms its structure and formatting to clean HTML which is then transformed into semantic content by the editor.

The [PasteFromOffice](../../api/module%5Fpaste-from-office%5Fpastefromoffice-PasteFromOffice.html) plugin also allows you to paste content from Google Docs. See the [pasting content from Google Docs guide](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) to learn more.

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--support-for-other-office-applications">

### Support for other office applications

At the current stage, the focus of `@ckeditor/ckeditor5-paste-from-office` and `@ckeditor/ckeditor5-paste-from-office-enhanced` packages is on supporting content that comes from Microsoft Word, Microsoft Excel, and [Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html). However, it does not mean that pasting from other similar applications (such as Microsoft PowerPoint) is not supported.

By default, CKEditor 5 will support pasting rich-text content from these applications, however, some styles and formatting may be lost, depending on the source application. Also, other minor bugs may appear.

You can find more information regarding compatibility with other applications in [this ticket](https://github.com/ckeditor/ckeditor5/issues/1184#issuecomment-409828069).

If you think that support for any of the applications needs improvements, please add 👍 and comments in the following issues:

* [Support pasting from Libre Office](https://github.com/ckeditor/ckeditor5/issues/2520).
* [Support pasting from Pages](https://github.com/ckeditor/ckeditor5/issues/2527).

Feel free to open a [new feature request](https://github.com/ckeditor/ckeditor5/issues/new/choose) for other similar applications, too!

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--automatic-content-filtering">

### Automatic content filtering

With CKEditor 5 you do not need to worry about pasting messy content from Microsoft Word (or any other possible sources). Thanks to the CKEditor 5 [custom data model](#ckeditor5/latest/framework/index.html), only content that is specifically handled by the loaded rich-text editor features will be preserved.

This means that if you did not enable, for instance, [font family and font size](#ckeditor5/latest/features/font.html) features, this sort of formatting will be automatically stripped off when you paste content from Microsoft Word and other sources (like other websites).

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--known-issues">

### Known issues

If the pasted document contains both images and styled text (like headings), images are sometimes not pasted properly. Unfortunately, for some operating systems, browsers, and Word versions the image data is not available in the clipboard in this case.

It is advised to try and paste the image separately from the body of the text if this error occurs.

If the image is represented in the Word content by the VML syntax (like this one: `<v:shape><v:imagedata src="...."/></v:shape>`), it will not be pasted either as this notation is not supported by CKEditor 5\. If you’d like to see this feature implemented, add a 👍 reaction to [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/9245).

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--related-features">

### Related features

CKEditor 5 supports a wider range of paste features, including:

* [Enhanced paste from Office](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) – Enhanced paste from Office is a premium version of the plugin that offers far greater capabilities.
* [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) – Paste content from Google Docs, maintaining the original formatting and structure.
* [Paste plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html) – Paste text without formatting that will inherit the style of the content it was pasted into.
* [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) – Convert Word files directly into HTML content. You can read more about the differences between the paste from Office and import from Word features in the [dedicated comparison guide](#ckeditor5/latest/features/converters/import-word/features-comparison.html).
* [Paste Markdown](#ckeditor5/latest/features/pasting/paste-markdown.html) – Paste Markdown-formatted content straight into the editor.

<a id="ckeditor5/latest/features/pasting/paste-from-office.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-paste-from-office>.

<a id="ckeditor5/latest/features/pasting/paste-markdown.html">source file: "ckeditor5/latest/features/pasting/paste-markdown.html"</a>

## Paste Markdown

The paste Markdown feature lets users paste Markdown-formatted content straight into the editor. It will be then converted into rich text on the fly.

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--demo">

### Demo

Paste some Markdown-formatted content into the demo editor below and see it turn into rich text on the fly. You can copy [this document](../../assets/markdown.txt) for convenience.

Output:

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--snippet-paste-from-markdown-output">

```

```

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--known-issues">

### Known issues

While the paste Markdown feature is already stable enough to use, it still needs some more testing. We are now focused on testing it in connection with other tools and plugins. If you have any observations, suggestions, or feedback you want to share, feel free to put them in [this GitHub issue](https://github.com/ckeditor/ckeditor5/issues/2321).

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--related-features">

### Related features

CKEditor 5 supports a wider range of paste features, including:

* [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) – Paste content from Microsoft Word and keep the original structure and formatting.
* [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) – Paste content from Google Docs, maintaining the original formatting and structure.
* [Paste plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html) – Paste text without formatting that will inherit the style of the content it was pasted into.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Format your content on the go with Markdown-like shortcodes.

<a id="ckeditor5/latest/features/pasting/paste-markdown.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-markdown-gfm>

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html">source file: "ckeditor5/latest/features/pasting/paste-plain-text.html"</a>

## Pasting plain text

With the plain text pasting feature, text pasted using the Ctrl/Cmd \+ Shift \+ V keystroke will match the formatting of the content you paste it into.

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--demo">

### Demo

Copy some text from one of the styled paragraphs below and press Ctrl/Cmd \+ Shift \+ V to paste it into another paragraph. See how the pasted text matches the paragraph’s style. Next, compare what happens when you paste the text without pressing Shift.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--additional-feature-information">

### Additional feature information

The plain text pasting feature is implemented by the `PastePlainText` plugin which is a part of the `Clipboard` plugin.

It detects the Ctrl/Cmd \+ Shift \+ V keystroke during the paste and causes the pasted text to inherit the styles of the content it was pasted into. In this sense, the feature can also be described as “pasting without formatting” – the source formatting of the pasted text gets replaced with the target formatting of the text it was pasted into.

Pasting plain text with a double line break will turn the break into a paragraph. A single line break will instead be turned into a soft break upon pasting.

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

The [PastePlainText](../../api/module%5Fclipboard%5Fpasteplaintext-PastePlainText.html) plugin will activate along with the clipboard plugin.

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--support-for-other-applications">

### Support for other applications

You can find more information regarding compatibility with other applications in [this ticket](https://github.com/ckeditor/ckeditor5/issues/1184#issuecomment-409828069).

If you think that support for any of the applications needs improvements, please add 👍 and comments in the following issues:

* [Support pasting from Excel](https://github.com/ckeditor/ckeditor5/issues/2513).
* [Support pasting from Libre Office](https://github.com/ckeditor/ckeditor5/issues/2520).
* [Support pasting from Pages](https://github.com/ckeditor/ckeditor5/issues/2527).

Feel free to open a [new feature request](https://github.com/ckeditor/ckeditor5/issues/new/choose) for other similar applications, too!

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--related-features">

### Related features

CKEditor 5 supports a wider range of paste features, including:

* [Paste Markdown](#ckeditor5/latest/features/pasting/paste-markdown.html) – Paste Markdown-formatted content straight into the editor.
* [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) – Paste content from Microsoft Word and keep the original structure and formatting.
* [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) – Paste content from Google Docs, maintaining the original formatting and structure.
* [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) – Convert Word files directly into HTML content.

<a id="ckeditor5/latest/features/pasting/paste-plain-text.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-clipboard>.

<a id="ckeditor5/latest/features/read-only.html">source file: "ckeditor5/latest/features/read-only.html"</a>

## Read-only support

CKEditor 5 offers an out-of-the-box read-only mode. You can use it to prevent users under certain circumstances from editing your content.

<a id="ckeditor5/latest/features/read-only.html--demo">

### Demo

Use the button below to toggle the read-only mode. Some features, like exports or search, are still functional in the read-only mode. Others, like the replace function, are disabled.

  
This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/read-only.html--additional-feature-information">

### Additional feature information

The feature does not require any additional plugin and the editor can be set into a read-only mode using the editor’s [Editor#enableReadOnlyMode()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-enableReadOnlyMode) method.

The read-only mode may have several applications. It may be used to impose user-based access restrictions, where a selected user or a group of users is only allowed to access the content for evaluation purposes but not change it.

The feature may also be used to view content that should not be edited, like financial reports, software logs, or reprinted stories. While not editable, this content will still be accessible for copying or for screen readers.

The editor can be switched to or out of the read-only mode by many features, under various circumstances. It supports a dedicated locking mechanism for the read-only mode. This solution enables easy control over the read-only mode even when many features try to turn it on or off at the same time, without conflicting with each other. It guarantees that the user will not make the editor content editable by accident (which could lead to errors).

<a id="ckeditor5/latest/features/read-only.html--hiding-the-toolbar-in-the-read-only-mode">

### Hiding the toolbar in the read-only mode

Some use cases might require hiding the editor toolbar when entering the read-only mode. This can be achieved easily with the following code:

```
ClassicEditor
    .create( {
        // The editor's configuration.
        // ...
    } )
    .then( editor => {
        const toolbarElement = editor.ui.view.toolbar.element;

        editor.on( 'change:isReadOnly', ( evt, propertyName, isReadOnly ) => {
            if ( isReadOnly ) {
                toolbarElement.style.display = 'none';
            } else {
                toolbarElement.style.display = 'flex';
            }
        } );
    } )
    .catch( error => {
        console.log( error );
    } );

```

When the button is clicked, the `editor.enableReadOnlyMode()` creates a lock that sets the read-only mode on the editor. This triggers the code showed above, which in turn hides the toolbar using CSS styles. After clicking the button once more, the `editor.disableReadOnlyMode()` is called, which removes the read-only lock and the editor’s and the toolbar is visible again. This approach will work both for classic and decoupled editors.

Use the demo below to see this code in action. Toggle the read-only mode with the button. You will see that the toolbar disappears in the read-only mode.

  
<a id="ckeditor5/latest/features/read-only.html--common-api">

### Common API

The editor provides the following API to manage the read-only mode:

* The [isReadOnly](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property is a read-only, observable property that allows you to check the `isReadOnly` value and react to its changes,
* The [Editor#enableReadOnlyMode( featureId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-enableReadOnlyMode) method turns on the read-only mode for the editor by creating a lock with given unique id.
* The [Editor#disableReadOnlyMode( featureId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-disableReadOnlyMode) method removes the read-only lock from the editor. The editor becomes editable when no lock is present on the editor anymore.

<a id="ckeditor5/latest/features/read-only.html--related-features">

### Related features

There are more features that help control user permissions in the WYSIWYG editor:

* [Restricted editing](#ckeditor5/latest/features/restricted-editing.html) – Define editable areas of the document for users with restricted editing rights.
* [Comments-only mode](#ckeditor5/latest/features/collaboration/comments/comments-only-mode.html) – Users can add comments to any part of the content instead of editing it directly.

<a id="ckeditor5/latest/features/read-only.html--common-api-2">

### Common API

The editor provides the following API to manage the read-only mode:

* The [isReadOnly](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property is a read-only, observable property that allows you to check the `isReadOnly` value and react to its changes,
* The [Editor#enableReadOnlyMode( featureId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-enableReadOnlyMode) method turns on the read-only mode for the editor by creating a lock with given unique id.
* The [Editor#disableReadOnlyMode( featureId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-disableReadOnlyMode) method removes the read-only lock from the editor. The editor becomes editable when no lock is present on the editor anymore.

<a id="ckeditor5/latest/features/read-only.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core>.

<a id="ckeditor5/latest/features/remove-format.html">source file: "ckeditor5/latest/features/remove-format.html"</a>

## Remove formatting

The remove format feature lets you quickly remove any text formatting applied using inline HTML elements and CSS styles, like [basic text styles](#ckeditor5/latest/features/basic-styles.html) (bold, italic) or [font family, size, and color](#ckeditor5/latest/features/font.html). This feature does not remove block-level formatting ([headings](#ckeditor5/latest/features/headings.html), [images](#ckeditor5/latest/features/images/images-overview.html)) or semantic data ([links](#ckeditor5/latest/features/link.html)).

<a id="ckeditor5/latest/features/remove-format.html--demo">

### Demo

Select the content you want to clean up and press the remove format button  in the toolbar.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/remove-format.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/remove-format.html--configuring-the-remove-format-feature">

### Configuring the remove format feature

This feature has no integration–level configuration. Once enabled, it works out–of–the–box with all [core editor features](#ckeditor5/latest/features/index.html).

<a id="ckeditor5/latest/features/remove-format.html--a-short-note-about-content-types-in-the-editor">

### A short note about content types in the editor

The remove format feature is intended to help users tidy up chunks of content from unnecessary formatting. Each editor feature brings its own content types to the WYSIWYG editor. If you do not want the unnecessary formatting to be enabled in the first place, you may want to consider reducing the number of features enabled in the editor.

Doing that will spare the users the pain of manually removing formatting every time they paste content from other programs and make the editing experience smoother. The narrower set of editor features also gives you more control over the content saved to the database and prevents the accidental use of the types of content you would rather not store in your application.

<a id="ckeditor5/latest/features/remove-format.html--integrating-with-editor-features">

### Integrating with editor features

In order for the remove formatting feature to work with custom content, you need to update the [schema](#ckeditor5/latest/framework/architecture/editing-engine.html--schema) by setting the `isFormatting` property on the custom [text attribute](#ckeditor5/latest/framework/architecture/editing-engine.html--text-attributes).

This is already done for most inline elements supported by the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) plugin and its derivatives such as the [Style](#ckeditor5/latest/features/style.html) plugin.

By default, formatting is not removed from the [link](#ckeditor5/latest/features/link.html) elements. To remove formatting from them as well, you need to create a [plugin](#ckeditor5/latest/getting-started/setup/configuration.html) that extends the schema and tells the editor that the `linkHref` text attribute produced by the link feature is a formatting attribute:

```
// A simple plugin that extends the remove format feature to consider links.
function RemoveFormatLinks( editor ) {
    // Extend the editor schema and mark the "linkHref" model attribute as formatting.
    editor.model.schema.setAttributeProperties( 'linkHref', {
        isFormatting: true
    } );
}

```

Enable the `RemoveFormatLinks` plugin in the [configuration](#ckeditor5/latest/getting-started/setup/configuration.html--adding-features) and run the editor:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [
            RemoveFormat,
            RemoveFormatLinks,
            // More plugins.
            // ...
        ],
        toolbar: [
            'removeFormat',
            // More toolbar items.
            // ...
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

From now on, the remove format button should also remove links in the content. [Learn more about attribute properties.](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-setAttributeProperties)

<a id="ckeditor5/latest/features/remove-format.html--related-features">

### Related features

CKEditor 5 has more features that can help you format your content:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – The essentials, like **bold**, _italic_, and others.
* [Font styles](#ckeditor5/latest/features/font.html) – Easily and efficiently control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Format painter](#ckeditor5/latest/features/format-painter.html) – Easily copy text formatting and apply it in a different place in the edited document.
* [Text alignment](#ckeditor5/latest/features/text-alignment.html) – Align your content left, align it right, center it, or justify.

<a id="ckeditor5/latest/features/remove-format.html--common-api">

### Common API

The [RemoveFormat](../api/module%5Fremove-format%5Fremoveformat-RemoveFormat.html) plugin registers the `'removeFormat'` UI button component and a command of the same name implemented by [RemoveFormatCommand](../api/module%5Fremove-format%5Fremoveformatcommand-RemoveFormatCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Removes all the formatting in the selection.
editor.execute( 'removeFormat' );

```

<a id="ckeditor5/latest/features/remove-format.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-remove-format>.

<a id="ckeditor5/latest/features/restricted-editing.html">source file: "ckeditor5/latest/features/restricted-editing.html"</a>

## Restricted editing

The restricted editing feature introduces two modes: the standard editing mode and the restricted editing mode. Users working in the restricted editing mode cannot change the content, except for parts marked as editable.

<a id="ckeditor5/latest/features/restricted-editing.html--demo">

### Demo

The demo below lets you emulate both the standard editing mode and the restricted editing mode.

Start by creating a template of the document in the standard editing mode. Select a section of the text and use the enable editing toolbar button  to turn a selected area into an editable region or remove an existing one.

Then switch to the restricted editing mode to see how the editable and non-editable regions behave.

**Mode:**

<a id="ckeditor5/latest/features/restricted-editing.html--mode-standard">

Standard

<a id="ckeditor5/latest/features/restricted-editing.html--mode-restricted">

Restricted

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/restricted-editing.html--additional-feature-information">

### Additional feature information

The restricted editing feature enables two editing modes:

* **Standard editing mode** – In this mode the user can edit the content and choose regions that should be editable in the restricted editing mode.
* **Restricted editing mode** – When you initialize the editor in this mode, the user can edit the content only within the regions chosen by the user in the standard editing mode. There changes allowed withing these fields can be configured.

There are two types of editable fields: inline and block.

* **Inline editable fields** only allow content editing with [features enabled in the restricted mode](#ckeditor5/latest/features/restricted-editing.html--enabling-commands-in-the-restricted-editing-mode). This kind of field can only hold inline content. They support only inline-type changes. Users can type, delete content, and format the text. However, no block-type editions are available. This means no splitting paragraphs (striking the Enter key) is allowed. Tables or block images cannot be added in this field, either.
* **Block editable fields** enable all content editing features loaded in the editor. Content inside the block can be anything, including lists, tables, images etc. (providing these features are loaded into the editor).

You can observe it in the [demo](#ckeditor5/latest/features/restricted-editing.html--demo) while switching between the inline and the block editable field – the number of active toolbar items will change.

Both block and inline fields can be inserted via the toolbar dropdown . The availability of one or both types of fields from the toolbar [can be configured](#ckeditor5/latest/features/restricted-editing.html--configuring-the-toolbar).

You can imagine a workflow where a certain group of users is responsible for creating templates of documents. At the same time, a second group of users can only fill the gaps (for example, fill in the missing data, like names, dates, product names, etc.).

By using this feature, the users of your application will be able to create template documents. In a certain way, you can use this feature to generate forms with rich-text capabilities. This kind of practical application is shown in the [How to create ready-to-print documents with CKEditor 5 pagination feature](https://ckeditor.com/blog/How-to-create-ready-to-print-documents-with-page-structure-in-WYSIWYG-editor---CKEditor-5-pagination-feature/) blog post.

<a id="ckeditor5/latest/features/restricted-editing.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration.

<a id="ckeditor5/latest/features/restricted-editing.html--running-the-standard-editing-mode">

#### Running the standard editing mode

To initialize the editor in the standard editing mode, add the [StandardEditingMode](../api/module%5Frestricted-editing%5Fstandardeditingmode-StandardEditingMode.html) plugin and add the `'restrictedEditingException:auto'` button to the toolbar:

<a id="ckeditor5/latest/features/restricted-editing.html--running-the-restricted-editing-mode">

#### Running the restricted editing mode

To initialize the editor in the restricted editing mode, add the [RestrictedEditingMode](../api/module%5Frestricted-editing%5Frestrictededitingmode-RestrictedEditingMode.html) plugin and add the `'restrictedEditing'` button to the toolbar:

<a id="ckeditor5/latest/features/restricted-editing.html--configuration">

### Configuration

You can configure which features should be available in the inline editing field. For instance, the following configuration allows the users to type, delete but also to bold text.

```
ClassicEditor
    .create( {
        // ... Other confituration options ...
        restrictedEditing: {
            allowedCommands: [ 'bold' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

**Note**: Typing and deleting text is always possible in restricted editing regions. For more information, check out the [config.restrictedEditing](../api/module%5Frestricted-editing%5Frestrictededitingconfig-RestrictedEditingConfig.html) documentation.

<a id="ckeditor5/latest/features/restricted-editing.html--enabling-commands-in-the-restricted-editing-mode">

#### Enabling commands in the restricted editing mode

The restricted editing mode allows modifying the editor content only in designated regions. Outside these regions, most of the editor commands are turned off by default. If you wish to enable some commands outside the restricted editing regions, you can use the [RestrictedEditingModeEditing.enableCommand()](../api/module%5Frestricted-editing%5Frestrictededitingmodeediting-RestrictedEditingModeEditing.html#function-enableCommand) method. You must execute this method in the [afterInit()](../api/module%5Fcore%5Fplugin-PluginInterface.html#function-afterInit) callback of an editor plugin.

<a id="ckeditor5/latest/features/restricted-editing.html--configuring-the-toolbar">

#### Configuring the toolbar

When configuring the toolbar item for inserting restricted editing fields in standard mode, you can choose to provide your users with access to inline, block or both types of fields. To add these to the toolbar, you should use the following toolbar item calls, respectively: `restrictedEditingException:dropdown` (both types of fields available), `restrictedEditingException:inline`, and `restrictedEditingException:block`. There is also the `restrictedEditingException:auto` button that switches between an inline and block depending on the selection.

Example toolbar configuration may look like the one below:

```
toolbar: [
    'restrictedEditingException:auto', '|',
    'heading', '|', 'bold', 'italic', 'link', '|',
    'bulletedList', 'numberedList', 'todolist', 'outdent', 'indent', '|',
    'blockQuote', 'insertImage', 'insertTable', '|',
    'undo', 'redo'
]

```

To configure the feature toolbar button for restricted mode, use the `restrictedEditing` call, instead. The Navigate editable regions button  allows for moving between previous/next editable fields.

Example toolbar configuration may look like the one below. Please note that whatever toolbar items maybe enable, the two different types of editable fields [will not support all of them.](#ckeditor5/latest/features/restricted-editing.html--additional-feature-information). From the example below, inline editable fields will only support bold, italic, link, and undo, while images, tables, and list will only be available for block type fields.

```
toolbar: {
    items: [
        'restrictedEditing', '|',
        'heading', '|', 'bold', 'italic', `link`, '|',
        'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent', '|',
        'insertImage', 'insertTable', '|',
        'undo', 'redo'
    ]
}

```

<a id="ckeditor5/latest/features/restricted-editing.html--legacy-toolbar-button">

##### Legacy toolbar button

The new toolbar items were introduced with version 47.2.0\. To retain full backwards compatibility, we have provided an alias toolbar item: `restrictedEditingException`. It is the old toolbar button call and it defaults to inline restricted editing field button. There is no need to change your configuration if you only want to use inline fields type.

<a id="ckeditor5/latest/features/restricted-editing.html--related-features">

### Related features

CKEditor 5 has more features that help you control user permissions:

* [Read-only](#ckeditor5/latest/features/read-only.html) – Turn the entire content of the editor read-only.
* [Track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Mark user changes in the content and show them as suggestions in the sidebar for acceptance or rejection.
* [Comments](#ckeditor5/latest/features/collaboration/comments/comments.html) – Users can add comments to any part of the content instead of editing it directly.

<a id="ckeditor5/latest/features/restricted-editing.html--common-api">

### Common API

The [StandardEditingMode](../api/module%5Frestricted-editing%5Fstandardeditingmode-StandardEditingMode.html) plugin registers:

* The `'restrictedEditingException:auto'` button that lets you mark regions as editable (either block or inline depending on the selection).
* The `'restrictedEditingException:dropdown'` button that lets you mark regions as editable.
* The `'restrictedEditingException:inline'` button that lets you mark inline regions as editable.
* The `'restrictedEditingException:block'` button that lets you mark block regions as editable.
* The `'restrictedEditingException'` button that lets you mark inline regions as editable (legacy alias).
* The ['restrictedEditingException'](../api/module%5Frestricted-editing%5Frestrictededitingexceptioncommand-RestrictedEditingExceptionCommand.html) command that allows marking inline regions as editable.
* The ['restrictedEditingExceptionBlock'](../api/module%5Frestricted-editing%5Frestrictededitingexceptionblockcommand-RestrictedEditingExceptionBlockCommand.html) command that allows marking block regions as editable.
* The ['restrictedEditingExceptionAuto'](../api/module%5Frestricted-editing%5Frestrictededitingexceptionautocommand-RestrictedEditingExceptionAutoCommand.html) command that calls either inline or block command depending on the selection.

The [RestrictedEditingMode](../api/module%5Frestricted-editing%5Frestrictededitingmode-RestrictedEditingMode.html) plugin registers:

* The `'restrictedEditing'` dropdown that lets you navigate between editable regions.
* The ['goToPreviousRestrictedEditingException'](../api/module%5Frestricted-editing%5Frestrictededitingmodenavigationcommand-RestrictedEditingModeNavigationCommand.html) and `'goToNextRestrictedEditingException'` commands that allow navigating between editable regions.

<a id="ckeditor5/latest/features/restricted-editing.html--real-time-collaboration">

### Real-time collaboration

When using [real-time collaboration](https://ckeditor.com/collaboration/real-time-collaborative-editing/), all the connected users should always be in the same mode. You cannot have a different list of plugins enabled among users of a single collaborative session.

<a id="ckeditor5/latest/features/restricted-editing.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-restricted-editing>.

<a id="ckeditor5/latest/features/select-all.html">source file: "ckeditor5/latest/features/select-all.html"</a>

## Select all

The select all feature lets you select the entire content using the Ctrl/Cmd+A keystroke or a toolbar button. This way you can clear or copy all the content in one move.

<a id="ckeditor5/latest/features/select-all.html--demo">

### Demo

Press Ctrl/Cmd+A or use the toolbar button  to select the entire content of the editor.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/select-all.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/select-all.html--related-features">

### Related features

* [Keyboard shortcuts](#ckeditor5/latest/features/accessibility.html--keyboard-shortcuts) – Check other popular keyboard shortcuts supported by CKEditor 5.

<a id="ckeditor5/latest/features/select-all.html--common-api">

### Common API

The [SelectAll](../api/module%5Fselect-all%5Fselectall-SelectAll.html) plugin registers the `'selectAll'` UI button component and the `'selectAll'` command implemented by [SelectAllCommand](../api/module%5Fselect-all%5Fselectallcommand-SelectAllCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Select the entire content of the editor.
editor.execute( 'selectAll' );

```

<a id="ckeditor5/latest/features/select-all.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-select-all>.

<a id="ckeditor5/latest/features/show-blocks.html">source file: "ckeditor5/latest/features/show-blocks.html"</a>

## Show blocks

The show blocks feature allows the content creators to visualize all block-level elements (except for widgets). It surrounds them with an outline and displays their element name in the top-left corner of the box.

<a id="ckeditor5/latest/features/show-blocks.html--demo">

### Demo

Toggle the block elements visibility with the show block  toolbar button to see the feature in action. The content remains editable, so you can see how the blocks adjust to the content structure on the go. These outlines are not visible in the [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) and [export to Word](#ckeditor5/latest/features/converters/export-word.html) features, so there is no need to remove them before exporting.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/show-blocks.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/show-blocks.html--known-issues">

### Known issues

* The show blocks feature does not support widgets, yet. It means it will currently not show block outlines for example for images or tables. Feel free to upvote 👍 [this issue on GitHub](https://github.com/ckeditor/ckeditor5/issues/14869) if it is important for you.
* At present, the show blocks feature is not yet fully compatible with the [pagination](#ckeditor5/latest/features/pagination/pagination.html) feature. Using these two together may result in errors.

<a id="ckeditor5/latest/features/show-blocks.html--related-features">

### Related features

Other CKEditor 5 features related to HTML editing that you may want to check:

* [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) – Allows you to enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.
* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) – Allows for viewing and editing the source code of the document in a handy modal window (compatible with all editor types) with syntax highlighting, autocompletion and more.
* [Full page HTML](#ckeditor5/latest/features/html/full-page-html.html) – Allows using CKEditor 5 to edit entire HTML pages, from `<html>` to `</html>`, including the page metadata.

<a id="ckeditor5/latest/features/show-blocks.html--common-api">

### Common API

The [ShowBlocks](../api/module%5Fshow-blocks%5Fshowblocks-ShowBlocks.html) plugin registers the `'showBlocks'` UI button component and the `'showBlocks'` command implemented by [ShowBlocksCommand](../api/module%5Fshow-blocks%5Fshowblockscommand-ShowBlocksCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Toggle the visibility of block-level elements outline.
editor.execute( 'showBlocks' );

```

<a id="ckeditor5/latest/features/show-blocks.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-show-blocks>.

<a id="ckeditor5/latest/features/slash-commands.html">source file: "ckeditor5/latest/features/slash-commands.html"</a>

## Slash commands

The slash commands feature lets you execute a predefined command by writing its name or alias directly in the editor. When you type a slash (/), the suggested commands are displayed in a panel next to it. You can also type a phrase after the / to filter the results in the panel and to easily find the desired command.

<a id="ckeditor5/latest/features/slash-commands.html--demo">

### Demo

Type the / character to invoke a panel with predefined commands. Then, filter the result list by typing more characters after the slash, for example: `/list`. Slash commands can also apply templates or styles defined in the editor.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/slash-commands.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/slash-commands.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/slash-commands.html--configuration">

### Configuration

Although the slash commands feature is based on the [mention](#ckeditor5/latest/features/mentions.html) feature, it does not require any additional configuration to work. In particular, the / marker is configured automatically as well as the list of [default slash commands](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandConfig.html#function-getDefaultCommands) that will work right away (as long as they are enabled in the editor).

However, if you want to modify this list, it is possible to easily [add](#ckeditor5/latest/features/slash-commands.html--adding-slash-commands) or [remove](#ckeditor5/latest/features/slash-commands.html--removing-slash-commands) commands through configuration. It is also possible to [limit the number of commands](#ckeditor5/latest/features/slash-commands.html--limiting-displayed-command-list) displayed in the panel.

<a id="ckeditor5/latest/features/slash-commands.html--adding-slash-commands">

#### Adding slash commands

It is possible to add both commands registered in the editor and commands that execute custom logic. The parameter you should use for custom commands is [slashCommand.extraCommands](../api/module%5Fslash-command%5Fslashcommandeditorconfig-SlashCommandEditorConfig.html#member-extraCommands).

<a id="ckeditor5/latest/features/slash-commands.html--editor-commands">

##### Editor commands

To add an editor command as a slash command, besides the [id](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-id) and the [title](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-title) you have to provide the [commandName](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-commandName) parameter. The example below shows how to add a `bold` slash command:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        slashCommand: {
            extraCommands: [
                {
                    id: 'bold',
                    title: 'Bold',
                    commandName: 'bold',
                    // ...
                },
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/slash-commands.html--proxy-commands">

##### Proxy commands

To add a proxy command (a command that executes custom logic), besides the [id](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-id) and the [title](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-title) you have to provide a callback function for the [execute](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-execute) parameter. If you do not provide an `execute` parameter for a proxy command, the editor will throw an error when the user tries to execute it.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        slashCommand: {
            extraCommands: [
                {
                    id: 'alert',
                    title: 'Alert',
                    execute: editor => { console.log( 'Custom logic was executed.' ) }
                    // ...
                },
                // More extra commands.
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/slash-commands.html--removing-slash-commands">

#### Removing slash commands

To remove a command from the default list of slash commands, add its name to the array of removed commands ([slashCommand.removeCommands](../api/module%5Fslash-command%5Fslashcommandeditorconfig-SlashCommandEditorConfig.html#member-removeCommands)). The command will only be removed from the list of [default slash commands](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandConfig.html#function-getDefaultCommands), and not from the editor.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        slashCommand: {
            removeCommands: [ 'heading', 'paragraph', /* ... */ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/slash-commands.html--limiting-displayed-command-list">

#### Limiting displayed command list

By default, all available slash commands are displayed in the panel. If you want to limit the number of commands displayed to the user, use the [slashCommand.dropdownLimit](../api/module%5Fslash-command%5Fslashcommandeditorconfig-SlashCommandEditorConfig.html#member-dropdownLimit) parameter. It will determine the number of displayed items.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        slashCommand: {
            dropdownLimit: 4
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/slash-commands.html--single-slash-command-configuration">

#### Single slash command configuration

There are some more optional parameters of a single slash command entry you might find useful when configuring your own commands:

* [aliases](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-aliases) – To extend command filtering in the panel.
* [description](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-description) – Helpful if a title is not descriptive enough.
* [icon](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-icon) – To visually customize your own command.
* [isEnabled](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-isEnabled) – To provide custom logic and decide when the command is displayed in the panel.

Here is an example of how you can use them:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        slashCommand: {
            extraCommands: [
                {
                    id: 'bold',
                    title: 'Bold',
                    execute: editor => { /* Custom logic. */ },
                    aliases: [ 'strong' ],
                    description: 'Style the text in bold.',
                    icon: customIcon,
                    isEnabled: editor => { /* Custom logic. */ }
                },
                // ...
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/slash-commands.html--sorting-and-filtering">

#### Sorting and filtering

By default, slash commands are sorted alphabetically by title. The order changes when the user starts filtering. Slash commands matched by [id](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-id) are displayed first, then sorted by [title](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-title), then by [aliases](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-aliases), and finally by [description](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-description).

<a id="ckeditor5/latest/features/slash-commands.html--integration-with-other-features">

#### Integration with other features

Slash commands are integrated with the [template](#ckeditor5/latest/features/template.html) and [style](#ckeditor5/latest/features/style.html) features. It means that all templates and styles can be applied also using the corresponding slash command.

<a id="ckeditor5/latest/features/slash-commands.html--related-features">

### Related features

You may want to check the following similar productivity features of CKEditor 5:

* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Lets you quickly apply formatting to the content you are writing.
* [Automatic text transformation](#ckeditor5/latest/features/text-transformation.html) – Enables automatic turning of snippets such as `(tm)` into `™` and `"foo"` into `“foo”`.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html">source file: "ckeditor5/latest/features/source-editing/source-editing-enhanced.html"</a>

## Enhanced source code editing

The enhanced source code editing feature allows for viewing and editing the source code of the document in a handy modal window (compatible with [all editor types](#ckeditor5/latest/getting-started/setup/editor-types.html)) with syntax highlighting, autocompletion and more.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--demo">

### Demo

Use any of the editors below to see the enhanced source code editing plugin in action. Please note that enhanced source code editing works with [editor types](#ckeditor5/latest/getting-started/setup/editor-types.html), taking advantage of the built–in modal system.

Toggle the source editing mode  and make some changes in the HTML code (for example, add a new paragraph or an ordered list). Then leave the source editing mode and see that the changes are present in the document content.

You can also use one of the many CKEditor 5 features available in the toolbar and check how they render in the HTML source. Notice the collapsible table of contents, available thanks to the [general HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature, which introduces HTML elements not yet covered by the official plugins.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--additional-feature-information">

### Additional feature information

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--themes">

#### Themes

The enhanced source code editing feature enables you to customize the look and feel of the editor containing source code, allowing for seamless visual integration with your application. You can use one of the [many already available themes](https://thememirror.net/) or create your own custom theme.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--adding-a-theme">

##### Adding a theme

To load a custom theme, set the [sourceEditingEnhanced.theme](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhancedconfig-SourceEditingEnhancedConfig.html#member-theme) configuration option to the name of the provided theme.

```
import { barf } from 'thememirror';

ClassicEditor
    .create( {
        // ... Other configuration options

        sourceEditingEnhanced: {
            theme: barf
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--creating-a-custom-theme">

##### Creating a custom theme

To learn how to create your own custom themes, take a look at the [official CodeMirror documentation](https://codemirror.net/examples/styling/).

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--code-completion">

#### Code completion

The feature provides code completion support for HTML tags and attributes. The attribute completion list is context-aware and will only show ones that are allowed in the current context. It will also help you close open HTML tags. Start typing and the list will appear next to the caret.

Use ↑ and ↓ to browse the list. Press Enter to select the item.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--code-folding">

#### Code folding

The feature allows you to fold and unfold parts of the document source code. This is especially useful when working with large documents.

Click the folding icon in the gutter to collapse or expand the code block. Use the Ctrl+Shift+\[ (⌘⇧\[ on macOS) and Ctrl+Shift+\] (⌘⇧\] on macOS) keyboard shortcuts to fold and unfold the code. Use Ctrl+Alt+\[ (⌘⌥\[ on macOS) and Ctrl+Alt+\] (⌘⌥\] on macOS) to fold and unfold all code blocks.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--bracket-and-tag-matching">

#### Bracket and tag matching

The feature highlights matching brackets in the source code. When you place the cursor next to a bracket, the matching bracket will be highlighted. If you move the caret inside a tag, the opening and closing tags will be highlighted. If a HTML tag is not closed properly, the editor will also highlight it to let you know.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--keyboard-shortcuts">

#### Keyboard shortcuts

The source editor supports multiple keyboard shortcuts to make your work more efficient. Please refer to the full list of available keyboard shortcuts in a [dedicated guide](#ckeditor5/latest/features/accessibility.html--keyboard-shortcuts).

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--markdown-source-view">

#### Markdown source view

The source editing plugin also works well with the [Markdown output](#ckeditor5/latest/features/markdown.html) plugin. You do not need any special configuration: just add the plugin to the editor, and the source editing mode will display Markdown instead of HTML.

To utilize the Markdown source editing mode, just add the [Markdown output](#ckeditor5/latest/features/markdown.html) plugin to the editor.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--limitations-and-incompatibilities">

### Limitations and incompatibilities

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--real-time-collaboration">

#### Real-time collaboration

Source editing used during real-time collaboration brings a severe risk of data loss in a way that may be difficult for a user to notice and understand.

After you switch to source editing, incoming changes performed by remote users are not reflected in the source code. When you switch back (saving the source code), **all changes done in the meantime by other users will be overwritten**.

Due to this risk, these features are not allowed to be used together by default. When both are added to the editor, it will throw an error. **You have to explicitly enable source editing mode for real-time collaboration, acknowledging this risk.**

To enable the features, set the [sourceEditingEnhanced.allowCollaborationFeatures](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhancedconfig-SourceEditingEnhancedConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--comments-and-track-changes">

#### Comments and track changes

The comments and track changes features use markers to mark affected parts of the document.

In the source editing mode, it is possible for a user to modify these markers’ boundaries. The user can change the range of a comment or tracked change, or remove them. This presents a potential problem related to users permissions.

The editor will show a warning in the browser’s console when these plugins and source editing plugin are used together.

To turn off the warning, set the [sourceEditingEnhanced.allowCollaborationFeatures](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhancedconfig-SourceEditingEnhancedConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--support-for-various-html-elements">

#### Support for various HTML elements

The editor will only save changes made to the document data source if it “understands” them. It means one of the loaded plugins must recognize the given syntax (HTML or Markdown). Any syntax unsupported by the editor will be filtered out upon save.

For example, if the editor does not have the [horizontal line](#ckeditor5/latest/features/horizontal-line.html) plugin loaded, the `<hr>` tag added in the document source will be removed upon exit from the source editing mode.

To avoid that, make sure that your editor configuration has all the necessary plugins that handle various HTML tags.

In many cases, to enable advanced modifications through the source editing, you might need to enable the [HTML embed](#ckeditor5/latest/features/html/html-embed.html) feature and the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature, or write a plugin that will enable a given HTML tag or attribute support.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--html-normalization">

#### HTML normalization

When the editor reads the source data, it converts the data to a normalized, high-level, abstract data model structure, on which it operates. This structure differs from the HTML or Markdown code.

Note, that the same document “state” may be described using HTML in various ways.

For example, `<strong><em>Foo</em></strong>` and `<i><b>Foo</b></i>` both produce the “**_Foo_**” text with bold and italic styling. Both will be represented the same when loaded to the internal editor data model.

When the editor data model is later converted back to the document source data, it will be normalized regardless of the original input. In effect, `<i><b>Foo</b></i>` will eventually become `<strong><em>Foo</em></strong>`.

This limitation is a direct consequence of the core editor architecture and cannot be worked around. Although it is possible to change the editor’s final output, the input data will always be normalized to that output format.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--revision-history">

#### Revision history

Saving the modified document source is internally executed through replacing the old data with the new one. As a consequence, it will be represented in revision history as a total replace change (insertion + deletion).

The editor will show a warning in the browser’s console when revision history and source editing are loaded together.

To turn the warning off, set the [sourceEditingEnhanced.allowCollaborationFeatures](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhancedconfig-SourceEditingEnhancedConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--restricted-editing">

#### Restricted editing

Restricted editing is not enforced in the source editing mode. The user will be able to edit any part of the document, as well as remove the markers that mark the boundaries of restricted areas.

The editor will show a warning in the browser’s console when restricted editing and source editing are loaded together.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--custom-themes">

#### Custom themes

Using custom `CodeMirror` themes is **not supported** with [CKEditor 5 installed from CDN](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-ckeditor-5-from-cdn).

The CDN build already includes a bundled version of `CodeMirror` and its dependencies. If you attempt to use a custom theme and install CodeMirror-related packages manually, some dependencies will be loaded **twice** — once from the CDN bundle and once from your own packages. This results in version mismatches, duplicated internal modules, and runtime errors.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--related-features">

### Related features

There are other source-related CKEditor 5 features you may want to check:

* [Source editing support](#ckeditor5/latest/features/source-editing/source-editing.html) – The open-source source editing feature for CKEditor 5\. Limited to the [classic editor](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor). only, does not support syntax highlighting, keyboard shortcuts, autocompletion, or themes.
* [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) – Allows you to enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.
* [Full page HTML](#ckeditor5/latest/features/html/full-page-html.html) – Allows using CKEditor 5 to edit entire HTML pages, from `<html>` to `</html>`, including the page metadata.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Allows embedding an arbitrary HTML snippet in the editor.
* [Markdown output](#ckeditor5/latest/features/markdown.html) – Allows for Markdown output instead of HTML output.

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--common-api">

### Common API

The [SourceEditingEnhanced](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhanced-SourceEditingEnhanced.html) plugin registers:

* The `'sourceEditingEnhanced'` UI button component.
* The `'editSource'` command implemented by [EditSourceCommand](../../api/module%5Fsource-editing-enhanced%5Fui%5Feditsourcecommand-EditSourceCommand.html).

You can execute the command using the [editor.execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Open the "Edit source" modal window.
editor.execute( 'editSource' );

```

<a id="ckeditor5/latest/features/source-editing/source-editing-enhanced.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-source-editing>.

<a id="ckeditor5/latest/features/source-editing/source-editing.html">source file: "ckeditor5/latest/features/source-editing/source-editing.html"</a>

## Source code editing

The source editing feature lets you view and edit the source of your document. This is the basic, open-source source code editing feature, only available for the Classic Editor type. You can also try the more advanced, premium [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) plugin that provides the functionality in a handy modal window with syntax highlighting and more in all editor types.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--demo">

### Demo

Use the editor below to see the source editing plugin in action. Toggle the source editing mode  and make some changes in the HTML code (for example, add a new paragraph or an ordered list). Then leave the source editing mode and see that the changes are present in the document content.

You can also use one of the many CKEditor 5 features available in the toolbar and check how they render in the HTML source. Notice the collapsible table of contents, available thanks to the [general HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature. The feature introduces HTML elements not yet covered by the official plugins.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

To utilize the Markdown source editing mode just add the [Markdown output](#ckeditor5/latest/features/markdown.html) plugin to the editor.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--limitations-and-incompatibilities">

### Limitations and incompatibilities

<a id="ckeditor5/latest/features/source-editing/source-editing.html--real-time-collaboration">

#### Real-time collaboration

Source editing used during real-time collaboration brings a severe risk of data loss in a way that may be difficult for a user to notice and understand.

After you switch to source editing, incoming changes performed by remote users are not reflected in the source code. When you switch back (saving the source code), **all changes done in the meantime by other users will be overwritten**.

Due to this risk, these features are not allowed to be used together by default. When both are added to the editor, it will throw an error. **You have to explicitly enable source editing mode for real-time collaboration, acknowledging this risk.**

To enable the features, set the [sourceEditing.allowCollaborationFeatures](../../api/module%5Fsource-editing%5Fsourceeditingconfig-SourceEditingConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--comments-and-track-changes">

#### Comments and track changes

The comments and track changes features use markers to mark affected parts of the document.

In the source editing mode, it is possible for a user to modify these markers’ boundaries. The user can change the range of a comment or tracked change, or remove them. This presents a potential problem related to users permissions.

The editor will show a warning in the browser’s console when these plugins and source editing plugin are used together.

To turn off the warning, set the [sourceEditing.allowCollaborationFeatures](../../api/module%5Fsource-editing%5Fsourceeditingconfig-SourceEditingConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--support-for-various-html-elements">

#### Support for various HTML elements

The editor will save changes made to the document data source only if it “understands” them. It means only when one of the loaded plugins recognizes the given syntax (HTML or Markdown). All syntax unsupported by the editor will be filtered out.

For example, if the editor does not have the [horizontal line](#ckeditor5/latest/features/horizontal-line.html) plugin loaded, the `<hr>` tag added in the document source will be removed upon exit from the source editing mode.

To avoid that, make sure that your editor configuration has all the necessary plugins that handle various HTML tags.

In many cases, to enable advanced modifications through the source editing, you might need to enable the [HTML embed](#ckeditor5/latest/features/html/html-embed.html) feature and the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) feature, or write a plugin that will enable a given HTML tag or attribute support.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--html-normalization">

#### HTML normalization

When the editor reads the source data, it converts the data to a normalized, high-level abstract data model structure, on which it operates. This structure differs from the HTML or Markdown code.

Note, that the same document “state” may be described using HTML in various ways.

For example, `<strong><em>Foo</em></strong>` and `<i><b>Foo</b></i>` both produce the “Foo” text with bold and italic styling. Both will be represented the same when loaded to the internal editor data model.

When the editor data model is later converted back to the document source data, it will be normalized regardless of what the original input was. In effect, `<i><b>Foo</b></i>` will eventually become `<strong><em>Foo</em></strong>`.

This limitation is a direct consequence of the core editor architecture and cannot be worked around. Although it is possible to change the editor final output, the input data will always be normalized to that output format.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--impact-on-the-editor-ui">

#### Impact on the editor UI

Editor features rely on high-level editor API which cannot be used when the source editing is active. Due to that, when you switch to the source editing mode, all toolbar buttons become disabled and all dialog windows are closed.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--revision-history">

#### Revision history

Saving the modified document source is internally executed through replacing the old data with the new one. As a consequence, it will be represented in revision history as a total replace change (insertion + deletion).

The editor will show a warning in the browser’s console when revision history and source editing are loaded together.

To turn the warning off, set the [sourceEditing.allowCollaborationFeatures](../../api/module%5Fsource-editing%5Fsourceeditingconfig-SourceEditingConfig.html#member-allowCollaborationFeatures) configuration flag to `true`.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--restricted-editing">

#### Restricted editing

Restricted editing is not enforced in the source editing mode. The user will be able to edit any part of the document, as well as remove the markers that mark the boundaries of restricted areas.

The editor will show a warning in the browser’s console when restricted editing and source editing are loaded together.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--markdown-source-view">

### Markdown source view

The source editing plugin also works well with the [Markdown output](#ckeditor5/latest/features/markdown.html) plugin. You do not need any special configuration: just add the plugin to the editor, and the source editing mode will display Markdown instead of HTML.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--related-features">

### Related features

There are other source-related CKEditor 5 features you may want to check:

* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) – Allows for viewing and editing the source code of the document in a handy modal window (compatible with all editor types) with syntax highlighting, autocompletion and more.
* [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) – Allows you to enable HTML features (elements, attributes, classes, styles) that are not supported by other dedicated CKEditor 5 plugins.
* [Full page HTML](#ckeditor5/latest/features/html/full-page-html.html) – Allows using CKEditor 5 to edit entire HTML pages, from `<html>` to `</html>`, including the page metadata.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Allows embedding an arbitrary HTML snippet in the editor.
* [Markdown output](#ckeditor5/latest/features/markdown.html) – Allows for Markdown output instead of HTML output.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--common-api">

### Common API

The [SourceEditing](../../api/module%5Fsource-editing%5Fsourceediting-SourceEditing.html) plugin registers:

* The `'sourceEditing'` UI button component.

<a id="ckeditor5/latest/features/source-editing/source-editing.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-source-editing>.

<a id="ckeditor5/latest/features/special-characters.html">source file: "ckeditor5/latest/features/special-characters.html"</a>

## Special characters

The special characters feature lets you insert **mathematical operators**, **currency symbols**, **punctuation**, **graphic symbols** (such as arrows or bullets), or Unicode letters typically not accessible from the keyboard (such as **umlauts** or **other diacritics**).

<a id="ckeditor5/latest/features/special-characters.html--demo">

### Demo

Use the special characters toolbar button  in the editor below to open a [configurable](#ckeditor5/latest/features/special-characters.html--configuration) panel with a table of selectable special characters.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/special-characters.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/special-characters.html--configuration">

### Configuration

By default, a few categories of special characters have been defined. You can easily customize the special characters available in your WYSIWYG editor installation by adding new categories, extending the existing ones, or removing them altogether.

<a id="ckeditor5/latest/features/special-characters.html--adding-a-new-category">

#### Adding a new category

You can define a new special characters category using the [SpecialCharacters#addItems()](../api/module%5Fspecial-characters%5Fspecialcharacters-SpecialCharacters.html#function-addItems) function.

For example, the following plugin adds the “Emoji” category to the special characters dropdown.

```
function SpecialCharactersEmoji( editor ) {
    editor.plugins.get( 'SpecialCharacters' ).addItems( 'Emoji', [
        { title: 'smiley face', character: '😊' },
        { title: 'rocket', character: '🚀' },
        { title: 'wind blowing face', character: '🌬️' },
        { title: 'floppy disk', character: '💾' },
        { title: 'heart', character: '❤️' }
    ], { label: 'Emoticons' } );
}

ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [
            SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersEmoji,
        ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

After adding the above plugin to the editor configuration, the new category will become available in the special characters dropdown.

Below you can see a demo based on the example shown above. Use the special characters toolbar button  and then select “Emoticons” from the dropdown. This will let you insert an emoji into the content.

<a id="ckeditor5/latest/features/special-characters.html--adding-characters-to-an-existing-category">

#### Adding characters to an existing category

By using the [SpecialCharacters#addItems()](../api/module%5Fspecial-characters%5Fspecialcharacters-SpecialCharacters.html#function-addItems) function you can also add new special characters to an existing category.

```
function SpecialCharactersExtended( editor ) {
    editor.plugins.get( 'SpecialCharacters' ).addItems( 'Mathematical', [
        { title: 'alpha', character: 'α' },
        { title: 'beta', character: 'β' },
        { title: 'gamma', character: 'γ' }
    ] );
}

ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [
            SpecialCharacters, SpecialCharactersEssentials, SpecialCharactersExtended,
        ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Below you can see a demo based on the example shown above. Use the special characters toolbar button  and then select “Mathematical” from the dropdown. You will see that the category now contains the additional Greek letters introduced by the configuration above.

<a id="ckeditor5/latest/features/special-characters.html--removing-categories">

#### Removing categories

The special characters feature exposes each category as a separate plugin. While the [SpecialCharactersEssentials](../api/module%5Fspecial-characters%5Fspecialcharactersessentials-SpecialCharactersEssentials.html) plugin can be used to conveniently include all of them, you can customize the category list by adding individual plugins with particular categories.

By default, the `@ckeditor/ckeditor5-special-characters` package provides special characters grouped into the following categories:

* [SpecialCharactersArrows](../api/module%5Fspecial-characters%5Fspecialcharactersarrows-SpecialCharactersArrows.html) – Arrows special characters.
* [SpecialCharactersCurrency](../api/module%5Fspecial-characters%5Fspecialcharacterscurrency-SpecialCharactersCurrency.html) – Currency special characters.
* [SpecialCharactersLatin](../api/module%5Fspecial-characters%5Fspecialcharacterslatin-SpecialCharactersLatin.html) – Latin special characters.
* [SpecialCharactersMathematical](../api/module%5Fspecial-characters%5Fspecialcharactersmathematical-SpecialCharactersMathematical.html) – Mathematical special characters.
* [SpecialCharactersText](../api/module%5Fspecial-characters%5Fspecialcharacterstext-SpecialCharactersText.html) – Text special characters.
* [SpecialCharactersEssentials](../api/module%5Fspecial-characters%5Fspecialcharactersessentials-SpecialCharactersEssentials.html) – Combines the plugins listed above.

For example, you can limit the categories to “Mathematical” and “Currency” only by picking the [SpecialCharactersMathematical](../api/module%5Fspecial-characters%5Fspecialcharactersmathematical-SpecialCharactersMathematical.html) and [SpecialCharactersCurrency](../api/module%5Fspecial-characters%5Fspecialcharacterscurrency-SpecialCharactersCurrency.html) plugins, like so:

Below you can see a demo based on the example shown above. After clicking the special characters toolbar button , you can see that it contains fewer categories compared to the other editors on this page.

<a id="ckeditor5/latest/features/special-characters.html--ordering-categories">

#### Ordering categories

The order of categories in the UI is determined by the order in which they were registered. However, depending on the context in which you use the editor, you might want to change this order, to make it easier to access frequently used characters.

The categories order can be customized using the [order](../api/module%5Fspecial-characters%5Fspecialcharactersconfig-SpecialCharactersConfig.html#member-order) array.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        plugins: [ SpecialCharacters, SpecialCharactersEssentials, ... ],
        specialCharacters: {
            order: [
                'Text',
                'Latin',
                'Mathematical',
                'Currency',
                'Arrows'
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/special-characters.html--common-api">

### Common API

The [SpecialCharacters](../api/module%5Fspecial-characters%5Fspecialcharacters-SpecialCharacters.html) plugin registers the UI button component (`'specialCharacters'`).

<a id="ckeditor5/latest/features/special-characters.html--contribute">

### Contribute

The source code of the feature is available at GitHub in <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-special-characters>.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html">source file: "ckeditor5/latest/features/spelling-and-grammar-checking.html"</a>

## Spelling, grammar, and punctuation checking

[WProofreader SDK](https://webspellchecker.com/wsc-proofreader) is an AI-driven, multi-language text correction tool. Spelling, grammar, and punctuation suggestions appear on hover as you type or in a separate dialog aggregating all mistakes and replacement suggestions in one place.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--demo">

### Demo

Use the toolbar button  to test the spell and grammar check feature in the editor below.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

The WProofreader badge in the bottom-right corner shows you the total number of mistakes detected. Hover an underlined word to display the WProofreader suggestions for any of the spelling and grammar mistakes found. The suggestion card allows the user to use the feature on the go. If you want to see an overview of all mistakes found, click the “Proofread in dialog” option in the toolbar dropdown. It will invoke a detached floating dialog, which is easy to navigate and perfect for dedicated proofreading sessions.

You can access the WProofreader settings from the toolbar, too. Set the primary language, create a spelling dictionary, and tweak some additional proofreading settings.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--additional-feature-information">

### Additional feature information

You can fine-tune WProofreader via the dedicated settings menu. Choose a primary language from a set of available ones. Create and manage additional custom dictionaries. You can add words to the user dictionary directly from the suggestion card, too. If needed, you can turn off the spell checker and enable it again with a single click.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--multi-language-support">

### Multi-language support

The [text part language](#ckeditor5/latest/features/language.html) feature lets the user set different languages to different portions of the content. The spell and grammar check feature offers full support for multilingual content. If you set the WProofreader language to Auto Detect (or set the `auto` language in the configuration), the feature will automatically recognize the language for a given sentence. It will then suggest spelling and grammar corrections specifically for that language, as shown in the demo above.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--check-types">

### Check types

WProofreader checks texts for spelling, grammar, and punctuation mistakes. The autodetect feature facilitates the correction of multilingual texts. Users do not have to manually switch languages to proofread documents with mixed language. Handy spelling autocorrect validates user texts on the fly. Autocomplete suggestions for English make the proofreading process fast and smooth. You can accept the predictive text with a right → arrow key.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--supported-languages-and-dictionaries">

### Supported languages and dictionaries

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--language-support">

#### Language support

The most popular languages used with WProofreader include: American English, Australian English, Arabic, Brazilian Portuguese, British English, Canadian English, Canadian French, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Italian, Indonesian, Norwegian Bokmål, Norwegian Nynorsk, Portuguese, Spanish, Swedish, Turkish, and Ukrainian.

There are more languages available from the WebSpellChecker site. Grammar checking is available for over 20 languages.

The AI-driven tools approach for English, German, and Spanish is a recent addition to the software. It offers a far better checking quality and generates proofreading suggestions based on the context of a sentence. It provides more suitable suggestions that address mistakes with 3 times the accuracy compared to a traditional mechanism.

Here you can check the [full list of supported languages](https://webspellchecker.com/supported-languages/).

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--specialized-dictionaries">

#### Specialized dictionaries

Apart from the language dictionaries, WebSpellChecker offers two specialized dictionaries: medical and legal.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--custom-dictionaries">

#### Custom dictionaries

You can use custom dictionaries in two ways.

One is the **user-level dictionary** that you can expand during regular use by adding new words. This is a perfect solution for users working on specific content that may contain slang or professional jargon.

The other is the so-called **company-level dictionary**. These pre-made dictionaries can be uploaded by system administrators or CKEditor 5 integrators and made available across the company, accessible for all users. This way you can share all the benefits of a user-generated dictionary among the team, making the proofreading process more structured and controlled.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--accessibility">

### Accessibility

The WProofreader UI is designed and oriented toward comfort and ease of use. The proofreading floating dialog can be moved around, addressing the needs of left-handed editors and right-to-left language users. The clear, simple design is more readable for users with vision impairments. You can also navigate and operate the dialog with a keyboard, eliminating the need to use a mouse or another pointing device.

The spell and grammar check is compliant with Web Content Accessibility Guidelines (WCAG) 2.1 and Section 508 accessibility standards.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--installation">

### Installation

WProofreader is delivered as a CKEditor 5 plugin, so you can combine it into an editor preset just like other features. To add this feature to your rich-text editor, install the [@webspellchecker/wproofreader-ckeditor5](https://www.npmjs.com/package/@webspellchecker/wproofreader-ckeditor5) package:

```
npm install --save @webspellchecker/wproofreader-ckeditor5

```

Then, add it to your plugin list and the toolbar configuration. Please note, that unlike native CKEditor 5 plugins, this one is imported from its own package. Also, that this import is different than the standard CKEditor 5 plugins import:

```
import { ClassicEditor } from 'ckeditor5';
import { WProofreader } from '@webspellchecker/wproofreader-ckeditor5';

import '@webspellchecker/wproofreader-ckeditor5/index.css';

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ WProofreader, /* ...], */ ],
        toolbar: [ 'wproofreader', /* ... */ ],
        wproofreader: {
            // Configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

At this step, you need to provide a proper configuration. You can use WProofreader either as a [cloud solution](#ckeditor5/latest/features/spelling-and-grammar-checking.html--wproofreader-cloud) or [hosted on your server](#ckeditor5/latest/features/spelling-and-grammar-checking.html--wproofreader-on-premises) (on-premises or in a private cloud).

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--wproofreader-cloud">

#### WProofreader Cloud

After signing up for a [trial or paid version](https://ckeditor.com/contact/), you will receive your service ID on your email. You can use it to activate the service.

Add the following configuration to your editor:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        wproofreader: {
            serviceId: 'your-service-ID',
            srcUrl: 'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js'
        }
    } )

```

Refer to the [official documentation](https://github.com/WebSpellChecker/wproofreader-ckeditor5#install-instructions) for more details about the cloud setup and available configuration options.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--wproofreader-on-premises">

#### WProofreader on-premises

After signing up for a [trial or paid version](https://ckeditor.com/contact/), you will receive access to the WebSpellChecker on-premises package to install it on your server.

You will need to add the following configuration to your editor:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        wproofreader: {
            serviceProtocol: 'https',
            serviceHost: 'localhost',
            servicePort: '443',
            servicePath: 'virtual_directory/api/',
            srcUrl: 'https://host_name/virtual_directory/wscbundle/wscbundle.js'
        }
    } )

```

Refer to the [official documentation](https://github.com/WebSpellChecker/wproofreader-ckeditor5#install-instructions) for more details about the server setup and available configuration options.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--configuration">

### Configuration

WProofreader configuration is set inside the CKEditor 5 configuration in the `wproofreader` object. Refer to the [WProofreader API](https://webspellchecker.com/docs/api/wscbundle/Options.html) for further information.

<a id="ckeditor5/latest/features/spelling-and-grammar-checking.html--contribute">

### Contribute

You can report issues and request features in the [official WProofreader for CKEditor 5 repository](https://github.com/WebSpellChecker/wproofreader-ckeditor5/issues).

<a id="ckeditor5/latest/features/style.html">source file: "ckeditor5/latest/features/style.html"</a>

## Styles

The style feature lets you apply pre-configured styles to elements in your content. It works by adding one or more CSS classes to an element to change its appearance or add semantic information.

<a id="ckeditor5/latest/features/style.html--demo">

### Demo

Use the demo below to test the styles feature. Select a passage or a header and try applying various styles.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

Configuration of the above demo 

The editor configuration:

```
// ...
style: {
    definitions: [
        {
            name: 'Article category',
            element: 'h3',
            classes: [ 'category' ]
        },
        {
            name: 'Title',
            element: 'h2',
            classes: [ 'document-title' ]
        },
        {
            name: 'Subtitle',
            element: 'h3',
            classes: [ 'document-subtitle' ]
        },
        {
            name: 'Info box',
            element: 'p',
            classes: [ 'info-box' ]
        },
        {
            name: 'Side quote',
            element: 'blockquote',
            classes: [ 'side-quote' ]
        },
        {
            name: 'Marker',
            element: 'span',
            classes: [ 'marker' ]
        },
        {
            name: 'Spoiler',
            element: 'span',
            classes: [ 'spoiler' ]
        },
        {
            name: 'Code (dark)',
            element: 'pre',
            classes: [ 'fancy-code', 'fancy-code-dark' ]
        },
        {
            name: 'Code (bright)',
            element: 'pre',
            classes: [ 'fancy-code', 'fancy-code-bright' ]
        }
    ]
},
// ...

```

The style sheet:

```
@import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&family=PT+Serif:ital,wght@0,400;0,700;1,400&display=swap');

.ck.ck-content {
    font-family: 'PT Serif', serif;
    font-size: 16px;
    line-height: 1.6;
    padding: 2em;
}

.ck-content .ck-horizontal-line {
    margin-bottom: 1em;
}

.ck.ck-content hr {
    width: 100px;
    border-top: 1px solid #aaa;
    height: 1px;
    margin: 1em auto;
}

.ck.ck-content h3.category {
    font-family: 'Bebas Neue';
    font-size: 20px;
    font-weight: bold;
    color: #d1d1d1;
    letter-spacing: 10px;
    margin: 0;
    padding: 0;
}

.ck.ck-content h2.document-title {
    font-family: 'Bebas Neue';
    font-size: 50px;
    font-weight: bold;
    margin: 0;
    padding: 0;
    border: 0;
}

.ck.ck-content h3.document-subtitle {
    font-size: 20px;
    color: #e91e63;
    margin: 0 0 1em;
    font-weight: normal;
    padding: 0;
}

.ck.ck-content p.info-box {
    --background-size: 30px;
    --background-color: #e91e63;
    padding: 1.2em 2em;
    border: 1px solid var(--background-color);
    background: linear-gradient(135deg, var(--background-color) 0%, var(--background-color) var(--background-size), transparent var(--background-size)), linear-gradient(135deg, transparent calc(100% - var(--background-size)), var(--background-color) calc(100% - var(--background-size)), var(--background-color));
    border-radius: 10px;
    margin: 1.5em 2em;
    box-shadow: 5px 5px 0 #ffe6ef;
}

.ck.ck-content blockquote.side-quote {
    font-family: 'Bebas Neue';
    font-style: normal;
    float: right;
    width: 35%;
    position: relative;
    border: 0;
    overflow: visible;
    z-index: 1;
    margin-left: 1em;
}

.ck.ck-content blockquote.side-quote::before {
    content: "“";
    position: absolute;
    top: -37px;
    left: -10px;
    display: block;
    font-size: 200px;
    color: #e7e7e7;
    z-index: -1;
    line-height: 1;
}

.ck.ck-content blockquote.side-quote p {
    font-size: 2em;
    line-height: 1;
}

.ck.ck-content blockquote.side-quote p:last-child:not(:first-child) {
    font-size: 1.3em;
    text-align: right;
    color: #555;
}

.ck.ck-content span.marker {
    background: yellow;
}

.ck.ck-content span.spoiler {
    background: #000;
    color: #000;
}

.ck.ck-content span.spoiler:hover {
    background: #000;
    color: #fff;
}

.ck.ck-content pre.fancy-code {
    border: 0;
    margin-left: 2em;
    margin-right: 2em;
    border-radius: 10px;
}

.ck.ck-content pre.fancy-code::before {
    content: "";
    display: block;
    height: 13px;
    background: url(data:image/svg+xml;base64,PHN2ZyBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1NCAxMyI+CiAgPGNpcmNsZSBjeD0iNi41IiBjeT0iNi41IiByPSI2LjUiIGZpbGw9IiNGMzZCNUMiLz4KICA8Y2lyY2xlIGN4PSIyNi41IiBjeT0iNi41IiByPSI2LjUiIGZpbGw9IiNGOUJFNEQiLz4KICA8Y2lyY2xlIGN4PSI0Ny41IiBjeT0iNi41IiByPSI2LjUiIGZpbGw9IiM1NkM0NTMiLz4KPC9zdmc+Cg==);
    margin-bottom: 8px;
    background-repeat: no-repeat;
}

.ck.ck-content pre.fancy-code-dark {
    background: #272822;
    color: #fff;
    box-shadow: 5px 5px 0 #0000001f;
}

.ck.ck-content pre.fancy-code-bright {
    background: #dddfe0;
    color: #000;
    box-shadow: 5px 5px 0 #b3b3b3;
}

```

<a id="ckeditor5/latest/features/style.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/style.html--configuration">

### Configuration

Configuring the styles feature takes two steps. First, you need to define the styles in the configuration file, for example:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        style: {
            definitions: [
                {
                    name: 'Article category',
                    element: 'h3',
                    classes: [ 'category' ]
                },
                {
                    name: 'Info box',
                    element: 'p',
                    classes: [ 'info-box' ]
                },
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Then, define the corresponding CSS styles for the document:

```
.ck.ck-content h3.category {
    font-family: 'Bebas Neue';
    font-size: 20px;
    font-weight: bold;
    color: #d1d1d1;
    letter-spacing: 10px;
    margin: 0;
    padding: 0;
}

.ck.ck-content p.info-box {
    padding: 1.2em 2em;
    border: 1px solid #e91e63;
    border-left: 10px solid #e91e63;
    border-radius: 5px;
    margin: 1.5em;
}

```

The editor will automatically distinguish text and block styles and group them in the dropdown.

<a id="ckeditor5/latest/features/style.html--known-issues">

### Known issues

At present, the style feature may clash with other features that bring in similar content (like headings). Problems with overlapping styles applied to the same element may also occur.

<a id="ckeditor5/latest/features/style.html--related-features">

### Related features

Check out also these CKEditor 5 features to gain better control over your content style and format:

* [Basic text styles](#ckeditor5/latest/features/basic-styles.html) – Apply the most frequently used formatting such as bold, italic, underline, etc.
* [Font styles](#ckeditor5/latest/features/font.html) – Control the font [family](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature), [size](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature), [text or background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features).
* [Headings](#ckeditor5/latest/features/headings.html) – Divide your content into sections.
* [Format painter](#ckeditor5/latest/features/format-painter.html) – Easily copy text formatting and apply it in a different place in the edited document.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.
* [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) – Enable additional HTML, such as `<style>` and `<classes>` attributes.

<a id="ckeditor5/latest/features/style.html--common-api">

### Common API

The [Style](../api/module%5Fstyle%5Fstyle-Style.html) plugin registers:

* The `'style'` command implemented by [StyleCommand](../api/module%5Fstyle%5Fstylecommand-StyleCommand.html).
* The `'style'` UI dropdown.

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Applies the style to the selected content.
// Executing the command again will remove the style from the selected content.
editor.execute( 'style', { styleName: 'Article category' } );

```

<a id="ckeditor5/latest/features/style.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-style>.

<a id="ckeditor5/latest/features/table-of-contents.html">source file: "ckeditor5/latest/features/table-of-contents.html"</a>

## Table of contents

The table of contents feature lets you insert a widget with a list of headings (section titles) that reflects the structure of the document. The list stays up–to–date automatically as the user works on the document. Clicking a list item navigates the user to the corresponding document section.

<a id="ckeditor5/latest/features/table-of-contents.html--demo">

### Demo

Create several headings in the editor and click the table of contents button  in the toolbar. Change the heading text or level to see the table of contents getting updated live.

<a id="ckeditor5/latest/features/table-of-contents.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

By default, the table of contents feature takes care of managing the heading IDs and creating proper links with a dedicated `href` attribute. The output data produced by this feature ensures that clicking a link in a table of contents will scroll to the corresponding heading in the content.

<a id="ckeditor5/latest/features/table-of-contents.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/table-of-contents.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you navigate the content of the editor:

* [Document outline](#ckeditor5/latest/features/document-outline.html) – Display the list of sections (headings) of the document next to the editor.
* [Content minimap](#ckeditor5/latest/features/minimap.html) – Navigate the document using a miniature overview map placed next to the editor.
* [Pagination](#ckeditor5/latest/features/pagination/pagination.html) – See the live preview of the document’s page breaks and quickly navigate between pages.

<a id="ckeditor5/latest/features/table-of-contents.html--common-api">

### Common API

The [TableOfContents](../api/module%5Fdocument-outline%5Ftableofcontents-TableOfContents.html) plugin registers:

* The `'tableOfContents'` UI button component.
* The `'insertTableOfContents'` command implemented by [TableOfContentsCommand](../api/module%5Fdocument-outline%5Ftableofcontents%5Ftableofcontentscommand-TableOfContentsCommand.html).

You can execute the command using the [editor.execute()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method:

```
// Insert the table of contents.
editor.execute( 'insertTableOfContents' );

```

<a id="ckeditor5/latest/features/tables/layout-tables.html">source file: "ckeditor5/latest/features/tables/layout-tables.html"</a>

## Layout tables

Layout tables are used to structure web page content spatially rather than for presenting tabular data. They allow integrators to create multi-column designs and precise positioning of elements on a page. This kind of functionality may be handy, for example, when preparing newsletter content. You can switch between [content tables](#ckeditor5/latest/features/tables/tables.html) and layout tables by using the table toggling feature.

<a id="ckeditor5/latest/features/tables/layout-tables.html--table-types-comparison">

### Table types comparison

The CKEditor 5 table feature offers several approaches and plugins responsible for the execution of tables. These include:

* [Regular content tables](#ckeditor5/latest/features/tables/tables.html) – Content tables provide the basic table experience for presentation of tabular data.
* [Table layout](#ckeditor5/latest/features/tables/layout-tables.html) – Layout tables are used to structure the content spatially rather than present content. They allow for creating multi-column designs and precise positioning of elements on a page.
* [Plain table output](../../api/module%5Ftable%5Fplaintableoutput-PlainTableOutput.html) – This plugin strips the `<figure>` tag from the table data. It is basically an email client compatibility feature.

|                  | Regular table                                 | Layout table                                       | Plain table output                                |
| ---------------- | --------------------------------------------- | -------------------------------------------------- | ------------------------------------------------- |
| Usage            | Used for presenting tabular data              | Used for creating layouts and multi-column designs | Stripped of <figure> tags for email compatibility |
| Purpose          | Rich formatting and tabular data presentation | Focused on content positioning and structure       | Simplified output for maximum interoperability    |
| Setup            | Default table type in CKEditor 5              | Available through toggling or direct insertion     | Available as an optional plugin                   |
| Markup influence | Affects editing view and output data          | Affects editing view and output data               | Affects only output data                          |

<a id="ckeditor5/latest/features/tables/layout-tables.html--demo">

### Demo

Check the editor below to see the layout tables plugin in action. Use the layout table  toolbar button to insert a new layout table.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/tables/layout-tables.html--table-toggling">

### Table toggling

There are several table types available in CKEditor 5\. To switch between these different table modes, you can use the table toggling feature. It allows users to change the type of an existing table by clicking it and selecting the desired table type. This enables seamless switching between presentation-focused content tables and layout-oriented tables without recreating the structure from scratch.

When a table is selected, you can toggle its type in one of two ways:

1. If the [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) plugin is enabled, the table properties button  will include a “Table type” dropdown option that allows switching between regular content tables and layout tables.
2. If the [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) plugin is not available, you can use the dedicated `tableType` toolbar button to change the table type.

Switching between table types preserves the content while adjusting the table’s behavior and styling to match its new purpose. Layout tables focus on spatial arrangement and design, while content tables emphasize data presentation.

<a id="ckeditor5/latest/features/tables/layout-tables.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuration">

### Configuration

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuring-the-preferred-type-for-loading-external-tables">

#### Configuring the preferred type for loading external tables.

By default, external tables are loaded using internal heuristics. This can be configured by setting the preferred table type for loading all external tables by setting the [config.table.tableLayout.preferredExternalTableType](../../api/module%5Ftable%5Ftableconfig-TableLayoutConfig.html#member-preferredExternalTableType) option to `content` or `layout`.

<a id="ckeditor5/latest/features/tables/layout-tables.html--stripping-the-figure-wrapper-from-content-tables">

#### Stripping the `<figure>` wrapper from content tables

By default, the `<figure>` wrapper is preserved on content tables. To strip the `<figure>` element, set the [config.table.tableLayout.stripFigureFromContentTable](../../api/module%5Ftable%5Ftableconfig-TableLayoutConfig.html#member-stripFigureFromContentTable) option to `true`.

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuring-the-table-toggle-feature">

#### Configuring the table toggle feature

To configure the table toggling feature, you have several options:

1. Include the [TableLayout](../../api/module%5Ftable%5Ftablelayout-TableLayout.html) plugin in your editor setup to enable toggling between table types.
2. Add the `tableType` button to your table content toolbar if you want a dedicated button for toggling.
3. For advanced UI integration scenarios, include both [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) and [TableToolbar](../../api/module%5Ftable%5Ftabletoolbar-TableToolbar.html) plugins, which will add the table type option to the table properties dropdown.

The table type can also be set programmatically through the editor’s API, making it suitable for integration with external controls or automated workflows.

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuring-table-toggle-with-tableproperties">

#### Configuring table toggle with `TableProperties`

When the [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) plugin is available, table type options will be integrated into the table properties dropdown:

This will add table toggling button to the table toolbar:

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuring-table-toggle-without-tableproperties">

#### Configuring table toggle without `TableProperties`

If the `TableProperties` plugin is not available, you can use the dedicated `tableType` button in the content toolbar to change table types:

<a id="ckeditor5/latest/features/tables/layout-tables.html--configuring-table-toggle-in-the-main-editor-toolbar">

#### Configuring table toggle in the main editor toolbar

You can configure the main editor toolbar to use the content and layout tables selector dropdown. This is handy if for some reason you do not want to use the table toolbar in your implementation.

This will add table toggling button to the main editor toolbar:

<a id="ckeditor5/latest/features/tables/layout-tables.html--related-features">

### Related features

There are other CKEditor 5 features you may want to check:

* [Email editing](#ckeditor5/latest/features/email-editing/email.html) – The email editing solution is a set of tools aimed at making the email composition a better and more effective experience.
* [Email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html) – The email configuration helper plugin is the best way to start writing and editing emails.

<a id="ckeditor5/latest/features/tables/layout-tables.html--common-api">

### Common API

The [TableLayout](../../api/module%5Ftable%5Ftablelayout-TableLayout.html) plugin registers the following command:

* [TableLayoutEditing](../../api/module%5Ftable%5Ftablelayout%5Ftablelayoutediting-TableLayoutEditing.html) – The layout table editing command.
* [TableLayoutUI](../../api/module%5Ftable%5Ftablelayout%5Ftablelayoutui-TableLayoutUI.html) – The layout table UI.
* [InsertTableLayoutCommand](../../api/module%5Ftable%5Fcommands%5Finserttablelayoutcommand-InsertTableLayoutCommand.html) – The `insertTableLayout` toolbar dropdown.

The [TableLayout](../../api/module%5Ftable%5Ftablelayout-TableLayout.html) plugin registers the following UI components:

* The `'tableType'` button that allows changing the type of a selected table.
* The `'tableType'` command implemented by [TableTypeCommand](../../api/module%5Ftable%5Ftablelayout%5Fcommands%5Ftabletypecommand-TableTypeCommand.html).

You can execute the command using the [editor.execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method. The command accepts a table type value (‘content’ or ‘layout’) as an argument.

```
// Change the selected table to a layout table.
editor.execute('tableType', 'layout' );

// Change the selected table to a content table.
editor.execute('tableType', 'content' );

```

Additionally, if the [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) plugin is loaded, the `'tableProperties'` button will be extended with a dropdown to select the table type, providing an alternative UI for changing the table type.

<a id="ckeditor5/latest/features/tables/layout-tables.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

<a id="ckeditor5/latest/features/tables/tables-caption.html">source file: "ckeditor5/latest/features/tables/tables-caption.html"</a>

## Table caption

The [TableCaption](../../api/module%5Ftable%5Ftablecaption-TableCaption.html) plugin lets you add captions to your tables. Table captions also improve accessibility as they are recognized by screen readers.

<a id="ckeditor5/latest/features/tables/tables-caption.html--demo">

### Demo

In the demo below, click the table caption to edit it. Once you click the caption, you can use the table toolbar button  to toggle the caption on and off.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/tables/tables-caption.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

By default, the table caption is placed above the table. You can change the placement by setting [caption-side](https://developer.mozilla.org/en-US/docs/Web/CSS/caption-side) in your [content styles](#ckeditor5/latest/getting-started/setup/css.html) for the `.ck-content .table > figcaption` style. Changing it to `caption-side: bottom` will display the caption below the table.

<a id="ckeditor5/latest/features/tables/tables-caption.html--alternative-html-configuration">

#### Alternative HTML configuration

By default, the plugin produces the `<figcaption>` HTML element to store the caption content. However, it is possible to use the `<caption>` element instead. To change it, use the [useCaptionElement](../../api/module%5Ftable%5Ftableconfig-TableCaptionConfig.html#member-useCaptionElement) configuration option:

```
table: {
    tableCaption: {
        useCaptionElement: true
        }
    }

```

<a id="ckeditor5/latest/features/tables/tables-caption.html--common-api">

### Common API

<a id="ckeditor5/latest/features/tables/tables-caption.html--ui-components">

#### UI components

The [TableCaption](../../api/module%5Ftable%5Ftablecaption-TableCaption.html) plugin registers the following UI component:

* The `toggleTableCaption` button

<a id="ckeditor5/latest/features/tables/tables-caption.html--toolbars">

##### Toolbars

[TableCaption](../../api/module%5Ftable%5Ftablecaption-TableCaption.html) plugin allows adding the `toggleTableCaption` item to the toolbar. It is possible to [configure](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableToolbar) its content.

<a id="ckeditor5/latest/features/tables/tables-caption.html--editor-commands">

#### Editor commands

| [Command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) name | Command class                                                                                                                   | Belongs to (top–level plugin)                                             |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| 'toggleTableCaption'                                                                             | [ToggleTableCaptionCommand](../../api/module%5Ftable%5Ftablecaption%5Ftoggletablecaptioncommand-ToggleTableCaptionCommand.html) | [TableCaption](../../api/module%5Ftable%5Ftablecaption-TableCaption.html) |

<a id="ckeditor5/latest/features/tables/tables-caption.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

<a id="ckeditor5/latest/features/tables/tables-installation.html">source file: "ckeditor5/latest/features/tables/tables-installation.html"</a>

## Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/tables/tables-installation.html--table-contextual-toolbar">

#### Table contextual toolbar

Easily control your tables employing a dedicated toolbar.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        table: {
            contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/tables/tables-installation.html--default-table-headers">

#### Default table headers

To make every inserted table have `n` number of rows and columns as table headers by default, set an optional table configuration property `defaultHeadings` as follows:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        table: {
            defaultHeadings: { rows: 1, columns: 1 }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Check the table with default headers applied to both the first row and the first column in the demo below. Click on the table and use the column properties  or the row properties  UI button to toggle the respective headers.

<a id="ckeditor5/latest/features/tables/tables-installation.html--enable-table-footers">

#### Enable table footers

To enable table footers, set the optional table configuration property `enableFooters` as follows:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        table: {
            enableFooters: true
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The option also enables UI for table footers. You can set a footer row similarly to the header row by using the switch button in the table toolbar.

<a id="ckeditor5/latest/features/tables/tables-installation.html--disallow-nesting-tables">

#### Disallow nesting tables

By default, the editor allows nesting a table inside another table’s cell.

To disallow nesting tables, you need to register an additional schema rule. It needs to be added before the data is loaded into the editor. Due to that, it is best to implement it as a plugin:

```
function DisallowNestingTables( editor ) {
    editor.model.schema.addChildCheck( ( context, childDefinition ) => {
        if ( childDefinition.name == 'table' && Array.from( context.getNames() ).includes( 'table' ) ) {
            return false;
        }
    } );
}

// Pass it via config.extraPlugins or config.plugins:

ClassicEditor
    .create( {
        // ... Other configuration options ...
        extraPlugins: [ DisallowNestingTables ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/tables/tables-installation.html--common-api">

### Common API

<a id="ckeditor5/latest/features/tables/tables-installation.html--ui-components">

#### UI components

The [Table](../../api/module%5Ftable%5Ftable-Table.html) plugins register the following UI components:

| [Component](#ckeditor5/latest/getting-started/setup/toolbar.html) name | Registered by |  | The 'insertTable' dropdown | [Table](../../api/module%5Ftable%5Ftable-Table.html) |
| ---------------------------------------------------------------------- | ------------- |  | -------------------------- | ---------------------------------------------------- |
| The 'tableColumn' dropdown                                             |               |  |                            |                                                      |
| The 'tableRow' dropdown                                                |               |  |                            |                                                      |
| The 'mergeTableCells' split button                                     |               |  |                            |                                                      |

<a id="ckeditor5/latest/features/tables/tables-installation.html--toolbars">

##### Toolbars

The [TableToolbar](../../api/module%5Ftable%5Ftabletoolbar-TableToolbar.html) plugin introduces two balloon toolbars for tables.

* The content toolbar shows up when a table cell is selected and it is anchored to the table. It is possible to [configure](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-contentToolbar) its content. Normally, the toolbar contains the table-related tools such as `'tableColumn'` and `'tableRow'` dropdowns and `'mergeTableCells'` split button.
* The table toolbar shows up when the whole table is selected, for instance using the widget handler. It is possible to [configure](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableToolbar) its content.

<a id="ckeditor5/latest/features/tables/tables-installation.html--editor-commands">

#### Editor commands

| [Command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) name | Command class                                                                                                      | Belongs to (top–level plugin)                        |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| 'insertTable'                                                                                    | [InsertTableCommand](../../api/module%5Ftable%5Fcommands%5Finserttablecommand-InsertTableCommand.html)             | [Table](../../api/module%5Ftable%5Ftable-Table.html) |
| 'insertTableColumnLeft'                                                                          | [InsertColumnCommand](../../api/module%5Ftable%5Fcommands%5Finsertcolumncommand-InsertColumnCommand.html)          |                                                      |
| 'insertTableColumnRight'                                                                         | [InsertColumnCommand](../../api/module%5Ftable%5Fcommands%5Finsertcolumncommand-InsertColumnCommand.html)          |                                                      |
| 'insertTableRowAbove'                                                                            | [InsertRowCommand](../../api/module%5Ftable%5Fcommands%5Finsertrowcommand-InsertRowCommand.html)                   |                                                      |
| 'insertTableRowBelow'                                                                            | [InsertRowCommand](../../api/module%5Ftable%5Fcommands%5Finsertrowcommand-InsertRowCommand.html)                   |                                                      |
| 'removeTableColumn'                                                                              | [RemoveColumnCommand](../../api/module%5Ftable%5Fcommands%5Fremovecolumncommand-RemoveColumnCommand.html)          |                                                      |
| 'removeTableRow'                                                                                 | [RemoveRowCommand](../../api/module%5Ftable%5Fcommands%5Fremoverowcommand-RemoveRowCommand.html)                   |                                                      |
| 'selectTableColumn'                                                                              | [SelectColumnCommand](../../api/module%5Ftable%5Fcommands%5Fselectcolumncommand-SelectColumnCommand.html)          |                                                      |
| 'selectTableRow'                                                                                 | [SelectRowCommand](../../api/module%5Ftable%5Fcommands%5Fselectrowcommand-SelectRowCommand.html)                   |                                                      |
| 'setTableColumnHeader'                                                                           | [SetHeaderColumnCommand](../../api/module%5Ftable%5Fcommands%5Fsetheadercolumncommand-SetHeaderColumnCommand.html) |                                                      |
| 'setTableRowHeader'                                                                              | [SetHeaderRowCommand](../../api/module%5Ftable%5Fcommands%5Fsetheaderrowcommand-SetHeaderRowCommand.html)          |                                                      |
| 'mergeTableCellRight'                                                                            | [MergeCellCommand](../../api/module%5Ftable%5Fcommands%5Fmergecellcommand-MergeCellCommand.html)                   |                                                      |
| 'mergeTableCellLeft'                                                                             | [MergeCellCommand](../../api/module%5Ftable%5Fcommands%5Fmergecellcommand-MergeCellCommand.html)                   |                                                      |
| 'mergeTableCellUp'                                                                               | [MergeCellCommand](../../api/module%5Ftable%5Fcommands%5Fmergecellcommand-MergeCellCommand.html)                   |                                                      |
| 'mergeTableCellDown'                                                                             | [MergeCellCommand](../../api/module%5Ftable%5Fcommands%5Fmergecellcommand-MergeCellCommand.html)                   |                                                      |
| 'splitTableCellVertically'                                                                       | [SplitCellCommand](../../api/module%5Ftable%5Fcommands%5Fsplitcellcommand-SplitCellCommand.html)                   |                                                      |
| 'splitTableCellHorizontally'                                                                     | [SplitCellCommand](../../api/module%5Ftable%5Fcommands%5Fsplitcellcommand-SplitCellCommand.html)                   |                                                      |

<a id="ckeditor5/latest/features/tables/tables-installation.html--table-alignment-in-output">

#### Table alignment in output

Table alignment in the editor’s output uses CSS classes by default. But, you can control it with the `table.tableProperties.alignment.useInlineStyles` property.

* When the property is `false` (default), output contains CSS classes.
* When the property is `true`, output contains inline styles.

The option applies to all five alignment options. Learn more about them in the [Table alignment](#ckeditor5/latest/features/tables/tables.html--table-alignment) section.

<a id="ckeditor5/latest/features/tables/tables-resize.html">source file: "ckeditor5/latest/features/tables/tables-resize.html"</a>

## Table column resize

The [TableColumnResize](../../api/module%5Ftable%5Ftablecolumnresize-TableColumnResize.html) plugin lets you resize tables and individual table columns. It gives you complete control over column width.

<a id="ckeditor5/latest/features/tables/tables-resize.html--demo">

### Demo

To resize a column, simply hover your pointer over the column edge until it gets highlighted. Drag the column edge until you achieve the desired size.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

The column resize feature is compatible with the [Export to Word](#ckeditor5/latest/features/converters/export-word.html) feature. The converter will respect the column width set in the editor and retain it in the created .DOCX file.

<a id="ckeditor5/latest/features/tables/tables-resize.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/tables/tables-resize.html--common-api">

### Common API

The [TableColumnResize](../../api/module%5Ftable%5Ftablecolumnresize-TableColumnResize.html) plugin does not register UI components.

<a id="ckeditor5/latest/features/tables/tables-resize.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

<a id="ckeditor5/latest/features/tables/tables-styling.html">source file: "ckeditor5/latest/features/tables/tables-styling.html"</a>

## Table and cell styling tools

CKEditor 5 comes with some additional tools that help you change the look of tables and table cells. You can control border color and style, background color, padding, or text alignment.

<a id="ckeditor5/latest/features/tables/tables-styling.html--demo">

### Demo

Put the caret anywhere inside the table to open the table toolbar. Click the table properties button  in the toolbar. A pop–up will open with options to shape the look of the entire table. The cell properties button  gives you access to styling options for individual table cells.

[Learn more](#ckeditor5/latest/features/tables/tables-styling.html--configuring-styling-tools) about configuring color palettes in the table styling pop–up interfaces.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/tables/tables-styling.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/tables/tables-styling.html--configuring-styling-tools">

### Configuring styling tools

Table and cell styling tools let you create tables with colorful backgrounds and borders. These colors can be picked using color palettes in the table properties  and cell properties  pop-ups. To help users choose the right colors for the content, you can pre-configure such color palettes, like in the editor below:

With the selection inside any table cell, use the table properties  and cell properties  buttons in the toolbar to check available styling and color options.

<a id="ckeditor5/latest/features/tables/tables-styling.html--customizing-color-palettes">

#### Customizing color palettes

You can use these specific configuration options to define customized color palettes for background and border colors to match your document:

* [tableProperties.borderColors](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableProperties) – Defines the color palette for table borders.
* [tableProperties.backgroundColors](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableProperties) – Defines the color palette for table background.
* [tableCellProperties.borderColors](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableCellProperties) – Defines the color palette for cell borders.
* [tableCellProperties.backgroundColors](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableCellProperties) – Defines the color palette for cell background.

For instance, to define the same color palette for all border and background configurations, use the following code snippet:

```
const customColorPalette = [
    {
        color: 'hsl(4, 90%, 58%)',
        label: 'Red'
    },
    {
        color: 'hsl(340, 82%, 52%)',
        label: 'Pink'
    },
    {
        color: 'hsl(291, 64%, 42%)',
        label: 'Purple'
    },
    {
        color: 'hsl(262, 52%, 47%)',
        label: 'Deep Purple'
    },
    {
        color: 'hsl(231, 48%, 48%)',
        label: 'Indigo'
    },
    {
        color: 'hsl(207, 90%, 54%)',
        label: 'Blue'
    },

    // More colors.
    // ...
];

ClassicEditor
    .create( {
        // ... Other configuration options ...
        table: {
            contentToolbar: [
                'tableColumn', 'tableRow', 'mergeTableCells',
                'tableProperties', 'tableCellProperties'
            ],

            // Set the palettes for tables.
            tableProperties: {
                borderColors: customColorPalette,
                backgroundColors: customColorPalette
            },

            // Set the palettes for table cells.
            tableCellProperties: {
                borderColors: customColorPalette,
                backgroundColors: customColorPalette
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/tables/tables-styling.html--default-table-and-table-cell-styles">

#### Default table and table cell styles

The table styles feature allows for configuring the default look of the tables in the editor. The configuration object should be synchronized with the [editor content styles](#ckeditor5/latest/getting-started/setup/css.html).

The **“Table properties”** and **“Table cell properties”** buttons in the toolbar will show the table and table cell properties applied to the table or table cells.

The style sheet for the editor displayed below looks as follows:

```
.ck-content figure.table:not(.layout-table) {
    float: left;
    width: 550px;
    height: 450px;
}

.ck-content figure.table:not(.layout-table) > table {
    border-style: dashed;
    border-color: hsl(90, 75%, 60%);
    border-width: 3px;
}

.ck-content figure.table:not(.layout-table) > table  > tbody > tr > td,
.ck-content figure.table:not(.layout-table) > table  > tbody > tr > th,
.ck-content figure.table:not(.layout-table) > table  > thead > tr > td,
.ck-content figure.table:not(.layout-table) > table  > thead > tr > th {
    text-align: center;
    vertical-align: bottom;
    padding: 10px
}

```

You must pass the same values to the editor configuration as:

* The [table.tableProperties.defaultProperties](../../api/module%5Ftable%5Ftableconfig-TablePropertiesOptions.html) object for the table properties.
* The [table.tableCellProperties.defaultProperties](../../api/module%5Ftable%5Ftableconfig-TableCellPropertiesOptions.html) object for the table cell properties.

```
const tableConfig = {
    table: {
        tableProperties: {
            // The default styles for tables in the editor.
            // They should be synchronized with the content styles.
            defaultProperties: {
                borderStyle: 'dashed',
                borderColor: 'hsl(90, 75%, 60%)',
                borderWidth: '3px',
                alignment: 'left',
                width: '550px',
                height: '450px'
            },
        },
        // The default styles for table cells in the editor.
        // They should be synchronized with the content styles.
        tableCellProperties: {
            defaultProperties: {
                horizontalAlignment: 'center',
                verticalAlignment: 'bottom',
                padding: '10px'
            }
        }
    }
};

```

You should align the table element to the `left` side by default. Its size should be `550x450px`. The border style should be `dashed`, `3px` of its width, and the color specified as `Light green`.

The content should be away about `10px` from the cell’s edges (`padding`), vertically aligned to `bottom` and horizontally to `center`.

The same will be applied to new tables and cells if they are inserted into the editor.

Read more about all supported properties for the [table](../../api/module%5Ftable%5Ftableconfig-TablePropertiesOptions.html) and [table cell](../../api/module%5Ftable%5Ftableconfig-TableCellPropertiesOptions.html) features in their API documentation.

<a id="ckeditor5/latest/features/tables/tables-styling.html--helper-lines-when-border-style-is-set-to-none">

#### Helper lines when border style is set to none

By default, when a table or table cell has an inline style such as `border: none` or `border-style: none`, the editor displays a dashed helper line to visually indicate the hidden border. This visualization is applied only in the editing view and does not affect the output HTML or the data stored by CKEditor 5.

The effect looks as follows:

If you prefer a true WYSIWYG experience or already implement your own border visualization logic, this behavior can be disabled using the [table.showHiddenBorders](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-showHiddenBorders) configuration option.

```
const tableConfig = {
    table: {
        showHiddenBorders: false
    }
};

```

When disabled, tables and cells with `border: none` will remain completely borderless in the editing view, matching their rendered output.

<a id="ckeditor5/latest/features/tables/tables-styling.html--common-api">

### Common API

<a id="ckeditor5/latest/features/tables/tables-styling.html--ui-components">

#### UI components

The [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) and [TableCellProperties](../../api/module%5Ftable%5Ftablecellproperties-TableCellProperties.html) plugins register the following UI components:

| [Component](#ckeditor5/latest/getting-started/setup/toolbar.html) name | Registered by                                                                                  |  | The 'tableProperties' button | [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |  | ---------------------------- | ---------------------------------------------------------------------------------- |
| The 'tableCellProperties' button                                       | [TableCellProperties](../../api/module%5Ftable%5Ftablecellproperties-TableCellProperties.html) |  |                              |                                                                                    |

<a id="ckeditor5/latest/features/tables/tables-styling.html--toolbars">

##### Toolbars

The [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html) and [TableCellProperties](../../api/module%5Ftable%5Ftablecellproperties-TableCellProperties.html) plugins allow adding the `tableProperties` and `tableCellProperties` items to the toolbar. You can [configure](../../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-tableToolbar) its content.

<a id="ckeditor5/latest/features/tables/tables-styling.html--editor-commands">

#### Editor commands

| [Command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) name | Command class                                                                                                                                                                   | Belongs to (top-level plugin)                                                                  |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 'tableBorderColor'                                                                               | [TableBorderColorCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftablebordercolorcommand-TableBorderColorCommand.html)                                         | [TableProperties](../../api/module%5Ftable%5Ftableproperties-TableProperties.html)             |
| 'tableBorderStyle'                                                                               | [TableBorderStyleCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftableborderstylecommand-TableBorderStyleCommand.html)                                         |                                                                                                |
| 'tableBorderWidth'                                                                               | [TableBorderWidthCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftableborderwidthcommand-TableBorderWidthCommand.html)                                         |                                                                                                |
| 'tableAlignment'                                                                                 | [TableAlignmentCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftablealignmentcommand-TableAlignmentCommand.html)                                               |                                                                                                |
| 'tableWidth'                                                                                     | [TableWidthCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftablewidthcommand-TableWidthCommand.html)                                                           |                                                                                                |
| 'tableHeight'                                                                                    | [TableHeightCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftableheightcommand-TableHeightCommand.html)                                                        |                                                                                                |
| 'tableBackgroundColor'                                                                           | [TableBackgroundColorCommand](../../api/module%5Ftable%5Ftableproperties%5Fcommands%5Ftablebackgroundcolorcommand-TableBackgroundColorCommand.html)                             |                                                                                                |
| 'tableCellBorderStyle'                                                                           | [TableCellBorderStyleCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellborderstylecommand-TableCellBorderStyleCommand.html)                         | [TableCellProperties](../../api/module%5Ftable%5Ftablecellproperties-TableCellProperties.html) |
| 'tableCellBorderColor'                                                                           | [TableCellBorderColorCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellbordercolorcommand-TableCellBorderColorCommand.html)                         |                                                                                                |
| 'tableCellBorderWidth'                                                                           | [TableCellBorderWidthCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellborderwidthcommand-TableCellBorderWidthCommand.html)                         |                                                                                                |
| 'tableCellHorizontalAlignment'                                                                   | [TableCellHorizontalAlignmentCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellhorizontalalignmentcommand-TableCellHorizontalAlignmentCommand.html) |                                                                                                |
| 'tableCellWidth'                                                                                 | [TableCellWidthCommand](../../api/module%5Ftable%5Ftablecellwidth%5Fcommands%5Ftablecellwidthcommand-TableCellWidthCommand.html)                                                |                                                                                                |
| 'tableCellHeight'                                                                                | [TableCellHeightCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellheightcommand-TableCellHeightCommand.html)                                        |                                                                                                |
| 'tableCellPadding'                                                                               | [TableCellPaddingCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellpaddingcommand-TableCellPaddingCommand.html)                                     |                                                                                                |
| 'tableCellBackgroundColor'                                                                       | [TableCellBackgroundColorCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellbackgroundcolorcommand-TableCellBackgroundColorCommand.html)             |                                                                                                |
| 'tableCellVerticalAlignment'                                                                     | [TableCellVerticalAlignmentCommand](../../api/module%5Ftable%5Ftablecellproperties%5Fcommands%5Ftablecellverticalalignmentcommand-TableCellVerticalAlignmentCommand.html)       |                                                                                                |

<a id="ckeditor5/latest/features/tables/tables-styling.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

<a id="ckeditor5/latest/features/tables/tables.html">source file: "ckeditor5/latest/features/tables/tables.html"</a>

## Tables in CKEditor 5 (overview)

The table feature provides tools for creating and editing tables. Tables are great for organizing data in a clear, visually appealing way or creating structured content. They are also great for making document layouts for applications such as newsletters or email editors. There are two basic types of tables available: content tables, described in this feature guide, and [layout tables](#ckeditor5/latest/features/tables/layout-tables.html) used to organize the content rather than present tabular data. You can easily [switch between these two types](#ckeditor5/latest/features/tables/layout-tables.html--table-toggling).

<a id="ckeditor5/latest/features/tables/tables.html--demo">

### Demo

Use the insert table button  to insert a new table into the content. Click inside the table to open a contextual toolbar. The toolbar lets you add or remove columns  and rows . You can also merge or split cells .

Try toggling the caption on and off . You can also change the properties of the entire table  or individual cells . To control the width of a column, click and drag its edge.

You may look for more interesting details in the [Tables in CKEditor 5](https://ckeditor.com/blog/feature-of-the-month-tables-in-ckeditor-5/) blog post after reading this guide.

<a id="ckeditor5/latest/features/tables/tables.html--basic-table-features">

### Basic table features

The basic table features allow users to insert tables into content, add or remove columns and rows and merge or split cells.

The [@ckeditor/ckeditor5-table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table) package contains multiple plugins that implement various table-related features. The [Table](../../api/module%5Ftable%5Ftable-Table.html) plugin is at the core of the ecosystem and it provides the table functionality. There are many other features that extend the editor capabilities:

<a id="ckeditor5/latest/features/tables/tables.html--table-selection">

### Table selection

The [TableSelection](../../api/module%5Ftable%5Ftableselection-TableSelection.html) plugin introduces support for the custom selection system for tables that lets you:

* Select an arbitrary rectangular table fragment – a few cells from different rows, a column (or a few of them) or a row (or multiple rows).
* Apply formatting or add a link to all selected cells at once.

The table selection plugin is loaded automatically by the `Table` plugin and can be tested in the [demo above](#ckeditor5/latest/features/tables/tables.html--demo).

<a id="ckeditor5/latest/features/tables/tables.html--table-alignment">

### Table alignment

You can move tables horizontally to create a desired document layout. There are five alignment options in tables:

* Left (block) : A table aligns to the left. The table does not influence the flow of other content.
* Center : A table is horizontally centered, with equal amounts of space on both sides.
* Right (block) : A table is aligned to the right. The table does not influence the flow of other content.
* Left (wrap) : A table aligns to the left, and other content wraps around it.
* Right (wrap) : A table aligns to the right, and other content wraps around it.

You can find all of those options in the [table properties balloon](#ckeditor5/latest/features/tables/tables.html--table-contextual-toolbar). The balloon displays after you click on a table. Use the [demo above](#ckeditor5/latest/features/tables/tables.html--demo) to test all those options.

You can also control how the alignment appears in the editor’s output. Learn more about it in the [Table alignment in output](#ckeditor5/latest/features/tables/tables-installation.html--table-alignment-in-output) section.

<a id="ckeditor5/latest/features/tables/tables.html--table-cell-type">

### Table cell type

Two types of table cells can contain content: data cells (the default type) and header cells. Header cells provide semantic labelling for rows or columns, helping the browser or a screen reader understand the data arrangement and relations.

To change cell type, click the cell and use the cell properties icon  from the table toolbar. Once there, choose the desired cell type.

To create a header row or column in your table, select all cells in the row or column and change their type to header. You will see the type change automatically in the row/column property dialog.

<a id="ckeditor5/latest/features/tables/tables.html--table-cell-scope">

### Table cell scope

Header cells can use the `scope` attribute to explicitly associate themselves with the related row or column, which helps screen readers understand the table structure.

This attribute is available only for header cells and is enabled by default. The editor assigns the `scope` attribute automatically based on a header cell’s position. If you prefer, you can change it manually in the cell properties balloon. The dropdown offers two explicit options:

* **Column header** – forces a header cell to describe the column and sets `scope="col"`.
* **Row header** – forces a header cell to describe the row and sets `scope="row"`.

To disable this behavior, set the [config.table.tableCellProperties.scopedHeaders](../../api/module%5Ftable%5Ftableconfig-TableCellPropertiesConfig.html#member-scopedHeaders) configuration option to `false`.

<a id="ckeditor5/latest/features/tables/tables.html--typing-around-tables">

### Typing around tables

To type before or after a table easily, select the table, then press the Arrow key (← or →) once, depending on where you want to add content – before or after. The table is no longer selected and whatever text you type will appear in the desired position.

<a id="ckeditor5/latest/features/tables/tables.html--nesting-tables">

### Nesting tables

CKEditor 5 allows nesting tables inside other table’s cells. This may be used for creating advanced charts or layouts based on tables. The nested table can be formatted just like a regular one.

<a id="ckeditor5/latest/features/tables/tables.html--demo-2">

#### Demo

You can test this feature in the demo below by adding a new table in the blank “abandoned” section at the bottom of the existing table. Click inside a cell and use the insert table button . A nested table will appear inside the cell.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/tables/tables.html--known-issues">

#### Known issues

While table nesting is fully functional, the Markdown code generated with the [Markdown output](#ckeditor5/latest/features/autoformat.html) feature will not properly render nested tables ([#9475](https://github.com/ckeditor/ckeditor5/issues/9475)). Feel free to upvote 👍 this issue on GitHub if it is important for you.

<a id="ckeditor5/latest/features/tables/tables.html--table-contextual-toolbar">

### Table contextual toolbar

The [TableToolbar](../../api/module%5Ftable%5Ftabletoolbar-TableToolbar.html) plugin introduces a contextual toolbar for table. The toolbar appears when a table or a cell is selected and contains various table-related buttons. These would typically include add or remove columns  and rows  and merge or split cells . If these features are configured, the toolbar will also contain buttons for captions  and table  and cell  properties.

The table selection plugin is loaded automatically by the `Table` plugin and can be tested in the [demo above](#ckeditor5/latest/features/tables/tables.html--demo). Learn more about configuring a contextual toolbar in the [Common API section](#ckeditor5/latest/features/tables/tables-installation.html--toolbars).

<a id="ckeditor5/latest/features/tables/tables.html--block-vs-inline-content-in-table-cells">

### Block vs inline content in table cells

The table feature allows for creating block content (like paragraphs, lists, headings, etc.) inside table cells. However, if a table cell contains just one paragraph and this paragraph has no special attributes (like text alignment), the cell content is considered “inline” and the paragraph is not rendered.

This means that a table cell can have two states: with inline content or with block content. The reason for this differentiation is that most tables contain only inline content (like the [demo](#ckeditor5/latest/features/tables/tables.html--demo) above) and it is common for “data tables” to not contain any block content. In such a scenario, printing out `<p>` elements would be semantically wrong and also unnecessary. There are, however, scenarios where the user wants to create, for example, a list inside a table cell and then the support for block content is necessary.

<a id="ckeditor5/latest/features/tables/tables.html--inline-content">

#### Inline content

The following is the model representation of table cells with inline content only (a single `<paragraph>` inside):

```
<table>
    <tableRow>
        <tableCell>
            <paragraph>Foo</paragraph>
        </tableCell>
        <tableCell>
            <paragraph>Bar</paragraph>
        </tableCell>
    </tableRow>
</table>

```

The above model structure will be rendered to the [data](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#function-getData) as:

```
<figure class="table">
    <table>
        <tbody>
            <tr>
                <td>Foo</td>
                <td>Bar</td>
            </tr>
        </tbody>
    </table>
</figure>

```

In the editing view (the editable container in which the user edits the content), additional `<span>` elements are created to compensate for the hidden `<paragraph>` elements:

```
<figure class="table">
    <table>
        <tbody>
            <tr>
                <td><span>Foo</span></td>
                <td><span>Bar</span></td>
            </tr>
        </tbody>
    </table>
</figure>

```

<a id="ckeditor5/latest/features/tables/tables.html--block-content">

#### Block content

If a table cell contains any other block content than a single `<paragraph>` with no attributes, these block elements will be rendered.

The following is a sample table with some block content (model representation):

```
<table>
    <tableRow>
        <tableCell>
            <paragraph>Foo</paragraph>
            <paragraph>Bar</paragraph>
        </tableCell>
        <tableCell>
            <heading1>Some title</heading1>
        </tableCell>
        <tableCell>
            <paragraph textAlign="right">Baz</paragraph>
        </tableCell>
    </tableRow>
</table>

```

The above model structure will be rendered to the data and to the editing view as:

```
<figure class="table">
    <table>
        <tbody>
            <tr>
                <td>
                    <p>Foo</p>
                    <p>Bar</p>
                </td>
                <td>
                    <h2>Some title</h2>
                </td>
                <td>
                    <p style="text-align: right;">Baz</p>
                </td>
            </tr>
        </tbody>
    </table>
</figure>

```

<a id="ckeditor5/latest/features/tables/tables.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

<a id="ckeditor5/latest/features/template.html">source file: "ckeditor5/latest/features/template.html"</a>

## Templates

The template feature allows you to insert predefined content structures into the document. Templates can provide both smaller portions of content (like a formatted table) and base structures for entire documents (for example, a formal letter template). Templates are a useful tool to speed up the writing process and maintain compliance with the company’s document and content policy.

<a id="ckeditor5/latest/features/template.html--demo">

### Demo

Click the template button  to open the dropdown and select the template you want to apply. You can search the templates by their titles.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/template.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/template.html--activating-the-feature">

#### Activating the feature

To use this premium feature, you need to activate it with proper credentials. Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details.

<a id="ckeditor5/latest/features/template.html--configuration">

### Configuration

The configuration of the feature is simply a list of [template definitions](../api/module%5Ftemplate%5Ftemplate-TemplateConfig.html#member-definitions).

An example configuration can be as follows:

```
{
    template: {
        definitions: [
            {
                title: 'Issue acknowledgement (plain text)',
                data: 'Dear customer, thank you for your report! The issue is currently being worked on by our development team.'
            },
            {
                title: 'Signature (multi-line)',
                data: '<p><b>Jane Doe</b></p><p>Marketing Specialist at <a href="https://example.com">Example.com</a></p>',
                description: 'Author signature with the link to the website.'
            },
            {
                title: 'Pricing table',
                data: '<figure class="table"><table><thead><tr><th style="text-align:center;">Feature</th><th style="background-color:hsl(90, 75%, 60%);text-align:center;">Free</th><th style="background-color:hsl(180, 75%, 60%);text-align:center;">Basic</th><th style="background-color:hsl(0, 75%, 60%);text-align:center;"><span style="color:hsl(0, 0%, 100%);">Professional</span></th><th style="background-color:hsl(270, 75%, 60%);text-align:center;"><span style="color:hsl(0, 0%, 100%);">Custom</span></th></tr></thead><tbody><tr><td style="text-align:center;">Feature #1</td><td style="background-color:hsl(90, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(180, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(0, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(270, 75%, 60%);text-align:center;">✅</td></tr><tr><td style="text-align:center;">Feature #2</td><td style="background-color:hsl(90, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(180, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(0, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(270, 75%, 60%);text-align:center;">✅</td></tr><tr><td style="text-align:center;">Feature #3</td><td style="background-color:hsl(90, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(180, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(0, 75%, 60%);text-align:center;">✅</td><td style="background-color:hsl(270, 75%, 60%);text-align:center;">✅</td></tr><tr><td style="text-align:center;">Feature #4</td><td style="background-color:hsl(90, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(180, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(0, 75%, 60%);text-align:center;">❌</td><td style="background-color:hsl(270, 75%, 60%);text-align:center;">✅</td></tr></tbody></table><figcaption>Pricing table</figcaption></figure>',
                icon: '<svg viewBox="0 0 45 45" fill="none" xmlns="http://www.w3.org/2000/svg"><mask id="a" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="2" y="2" width="41" height="41"><rect x="2" y="2" width="41" height="41" rx="5" fill="#59A5FF"/></mask><g mask="url(#a)"><rect x="2" y="2" width="41" height="41" rx="5" fill="#444"/><path fill="#ECECEC" d="M4 17h11v11H4z"/><path fill="#A9E6FA" d="M17 17h11v11H17z"/><path fill="#ECECEC" d="M30 17h11v11H30z"/><path d="M4 7a3 3 0 0 1 3-3h31a3 3 0 0 1 3 3v8H4V7Z" fill="#FF1A88"/><path d="M4 30h11v11H7a3 3 0 0 1-3-3v-8ZM17 30h11v11H17z" fill="#A9E6FA"/><path d="M30 30h11v8a3 3 0 0 1-3 3h-8V30Z" fill="#ECECEC"/></g></svg>',
                description: 'Product pricing table that compares individual plans.'
            },
            // More template definitions.
            // ...
        ]
    }
}

```

<a id="ckeditor5/latest/features/template.html--related-features">

### Related features

Here are some more CKEditor 5 features that can help you work with predefined content blocks and documents:

* [Restricted editing](#ckeditor5/latest/features/restricted-editing.html) – Define editable areas of the document for users with restricted editing rights.
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html) – Embed an arbitrary HTML snippet in the editor.
* The [export to Word](#ckeditor5/latest/features/converters/export-word.html) feature allows you to generate editable `.docx` files out of your editor-created content.
* The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature allows you to generate portable PDF files out of your editor-created content.

<a id="ckeditor5/latest/features/template.html--common-api">

### Common API

The [Template](../api/module%5Ftemplate%5Ftemplate-Template.html) plugin registers:

* The `'insertTemplate'` UI dropdown component.
* The `'insertTemplate'` command implemented by [TemplateCommand](../api/module%5Ftemplate%5Ftemplatecommand-TemplateCommand.html).

You can execute the command to insert arbitrary content into the editor at the user selection:

```
editor.execute( 'insertTemplate', '<p>Content of the template</p>' );

```

<a id="ckeditor5/latest/features/text-alignment.html">source file: "ckeditor5/latest/features/text-alignment.html"</a>

## Text alignment

The alignment feature lets you align your content to the left or right as well as center or justify it.

<a id="ckeditor5/latest/features/text-alignment.html--demo">

### Demo

Click inside a paragraph or a header and use the toolbar dropdown  to change the alignment of the element.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/text-alignment.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/text-alignment.html--configuring-alignment-options">

### Configuring alignment options

<a id="ckeditor5/latest/features/text-alignment.html--defining-available-options">

#### Defining available options

It is possible to configure which alignment options are available in the editor by setting the [alignment.options](../api/module%5Falignment%5Falignmentconfig-AlignmentConfig.html#member-options) configuration option. You can choose from `'left'`, `'right'`, `'center'`, and `'justify'`.

For example, the following editor will support two alignment options: to the left and to the right:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        alignment: {
            options: [ 'left', 'right' ]
        },
        toolbar: [
            'heading', '|', 'bulletedList', 'numberedList', 'alignment', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/text-alignment.html--using-classes-instead-of-inline-style">

#### Using classes instead of inline style

By default, alignment is set inline using the `text-align` CSS property. If you wish the feature to output more semantic content that uses classes instead of inline styles, you can specify class names by using the `className` property in `config.alignment.options` and style them by using a style sheet.

The following configuration will set `.my-align-left` and `.my-align-right` to left and right alignment, respectively.

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        alignment: {
            options: [
                { name: 'left', className: 'my-align-left' },
                { name: 'right', className: 'my-align-right' }
            ]
        },
        toolbar: [
            'heading', '|', 'bulletedList', 'numberedList', 'alignment', 'undo', 'redo'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/text-alignment.html--configuring-the-toolbar">

### Configuring the toolbar

You can choose to use the alignment dropdown (`'alignment'`) or configure the toolbar to use separate buttons for each of the options:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        toolbar: [
            'heading', '|', 'alignment:left', 'alignment:right', 'alignment:center', 'alignment:justify'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/text-alignment.html--related-features">

### Related features

CKEditor 5 has more features that can help you organize your content:

* [Document title](#ckeditor5/latest/features/title.html) – Clearly divide your content into a title and body.
* [Headings](#ckeditor5/latest/features/headings.html) – Split your content into logical sections.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Organize your content into visually separated blocks, indent crucial paragraphs, etc.
* [Block quote](#ckeditor5/latest/features/block-quote.html) – Include block quotations or pull quotes in the rich-text content.
* [Remove format](#ckeditor5/latest/features/remove-format.html) – Easily clean basic text formatting.

<a id="ckeditor5/latest/features/text-alignment.html--common-api">

### Common API

The [Alignment](../api/module%5Falignment%5Falignment-Alignment.html) plugin registers:

* Dropdown: `'alignment'`.
* Buttons: `'alignment:left'`, `'alignment:right'`, `'alignment:center'`, `'alignment:justify'`.  
The number of options and their names are based on the [alignment.options](../api/module%5Falignment%5Falignmentconfig-AlignmentConfig.html#member-options) configuration option.
* Command: `'alignment'`:  
You can align the currently selected block(s) by executing one of these commands:  
```  
editor.execute( 'alignment', { value: 'center' } );  
```

<a id="ckeditor5/latest/features/text-alignment.html--content-compatibility">

### Content compatibility

The [Alignment](../api/module%5Falignment%5Falignment-Alignment.html) plugin provides support for the deprecated `align` attribute.

Block elements such as `<p>` with the `align` attribute are accepted by the plugin, but the editor always returns the markup in a modern format, so the transformation is one way only.

<a id="ckeditor5/latest/features/text-alignment.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-alignment>.

<a id="ckeditor5/latest/features/text-transformation.html">source file: "ckeditor5/latest/features/text-transformation.html"</a>

## Automatic text transformation (autocorrect)

The text transformation feature enables autocorrection. It automatically changes predefined text fragments into their improved forms.

<a id="ckeditor5/latest/features/text-transformation.html--demo">

### Demo

Type snippets such as `(c)`, `3/4`, `!=`, `---`, `"foo"` into the editor below and see how they get transformed into their typographically nicer forms. You can see the complete list of predefined transformations in the [TextTransformationConfig](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html) documentation.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/text-transformation.html--additional-feature-information">

### Additional feature information

Here are some examples of snippets changed by the text transformation feature:

| From  | To    |
| ----- | ----- |
| (tm)  | ™     |
| 1/2   | ½     |
| \->   | →     |
| \--   | –     |
| "foo" | “foo” |

This feature comes pre-configured with a set of the most popular transformations. You can, however, remove existing ones or add your own autocorrect entries.

While most often this feature is used to insert special characters that are not present on your keyboard, you can also use it to achieve other goals. For instance, you can improve the users’ productivity by configuring it to expand some abbreviations (like team or company names) into their full forms.

You may find interesting details and usage examples in the [Automatic text transformation in CKEditor 5](https://ckeditor.com/blog/feature-of-the-month-automatic-text-transformation-in-ckeditor-5/) blog post after reading this guide.

<a id="ckeditor5/latest/features/text-transformation.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/text-transformation.html--configuring-transformations">

### Configuring transformations

This feature comes pre-configured with a set of transformations. You can find the list of them in the [TextTransformationConfig](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html) documentation.

By using the options defined below you can extend, limit, or override this list:

* [typing.transformations.include](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html#member-include) – Overrides the default configuration. When overriding the default configuration you can reuse the predefined transformations (by using their names that you can find in the [TextTransformationConfig](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html) documentation) and write custom transformations.
* [typing.transformations.remove](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html#member-remove) – Removes predefined transformations.
* [typing.transformations.extra](../api/module%5Ftyping%5Ftypingconfig-TextTransformationConfig.html#member-extra) – Adds your custom transformations to the predefined ones.

<a id="ckeditor5/latest/features/text-transformation.html--example-using-transformationsinclude">

#### Example: Using `transformations.include`

For instance, to use the transformations from the “quotes” and “typography” groups and to turn `CKE` into `CKEditor`, you can use the `transformations.include` property like this:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        typing: {
            transformations: {
                include: [
                    // Use only the 'quotes' and 'typography' groups.
                    'quotes',
                    'typography',

                    // Plus some custom transformation.
                    { from: 'CKE', to: 'CKEditor' }
                ],
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/text-transformation.html--example-using-transformationsremove-and-extra">

#### Example: Using `transformations.remove` and `extra`

Another example, removing some transformations and adding some extra ones:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        typing: {
            transformations: {
                remove: [
                    // Do not use the transformations from the
                    // 'symbols' and 'quotes' groups.
                    'symbols',
                    'quotes',

                    // As well as the following transformations.
                    'arrowLeft',
                    'arrowRight'
                ],

                extra: [
                    // Add some custom transformations, for example, for emojis.
                    { from: ':)', to: '🙂' },
                    { from: ':+1:', to: '👍' },
                    { from: ':tada:', to: '🎉' },

                    // You can also define patterns using regular expressions.
                    // Note: The pattern must end with `$` and all its fragments must be wrapped
                    // with capturing groups.
                    // The following rule replaces ` "foo"` with ` «foo»`.
                    {
                        from: /(^|\s)(")([^"]*)(")$/,
                        to: [ null, '«', null, '»' ]
                    },

                    // Finally, you can define `to` as a callback.
                    // This (naive) rule will auto-capitalize the first word after a period, question mark, or an exclamation mark.
                    {
                        from: /([.?!] )([a-z])$/,
                        to: matches => [ null, matches[ 1 ].toUpperCase() ]
                    }
                ],
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

You can read more about the format of transformation rules in [TextTypingTransformationDescription](../api/module%5Ftyping%5Ftypingconfig-TextTypingTransformationDescription.html).

You can test these custom rules in the demo. Try typing `:)` or `:+1:` and see how the text gets transformed into emojis. You can also write some sentences to test how the editor capitalizes words after a period, a quotation mark, or an exclamation mark.

<a id="ckeditor5/latest/features/text-transformation.html--related-features">

### Related features

In addition to enabling automatic text transformations, you may want to check the following productivity features:

* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Quickly apply formatting to the content you are writing.
* [Autolink](#ckeditor5/latest/features/link.html--autolink-feature) – Turns the links and email addresses typed or pasted into the editor into active URLs.
* [Slash commands](#ckeditor5/latest/features/slash-commands.html) – Execute a predefined command by writing its name or alias directly in the editor.
* [Mentions](#ckeditor5/latest/features/mentions.html) – Brings support for smart autocompletion.

<a id="ckeditor5/latest/features/text-transformation.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-typing>.

<a id="ckeditor5/latest/features/title.html">source file: "ckeditor5/latest/features/title.html"</a>

## Document title

The title feature lets you add a single title field at the beginning of your document. This way you can clearly divide your content into the title and body sections.

<a id="ckeditor5/latest/features/title.html--demo">

### Demo

Use the editor below to create a document with distinct title and body sections. You can check the content of the title and body elements in the console below.

<a id="ckeditor5/latest/features/title.html--title-console%5F%5Ftitle">

```

```

<a id="ckeditor5/latest/features/title.html--title-console%5F%5Fbody">

```

```

<a id="ckeditor5/latest/features/title.html--title-console%5F%5Fdata">

```

```

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/title.html--keyboard-navigation">

### Keyboard navigation

The title plugin lets you move from the title to the body element using the Tab key, providing form-like experience. When the selection is at the beginning of the first body element, you can go back to the title element using Shift+Tab. You can also use Enter and Backspace keys to move the caret between the title and the body.

<a id="ckeditor5/latest/features/title.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/title.html--placeholder-integration">

### Placeholder integration

The title plugin is integrated with the [placeholder](#ckeditor5/latest/features/editor-placeholder.html) configuration. If you define it, the placeholder text will be used for the body element.

To change the title placeholder, use the [title.placeholder](../api/module%5Fheading%5Ftitle-HeadingTitleConfig.html#member-placeholder) configuration option. For instance:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        title: {
            placeholder: 'My custom placeholder for the title'
        },
        root: {
            placeholder: 'My custom placeholder for the body'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/features/title.html--html-structure">

### HTML structure

When you call [editor.getData()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData), the document title will be represented as the following HTML:

```
<h1>Feasibility Study</h1>

```

<a id="ckeditor5/latest/features/title.html--model-representation">

#### Model representation

In the CKEditor 5 data model the document title is represented as follows:

```
<title>
    <title-content>
        Feasibility Study
    </title-content>
</title>

```

<a id="ckeditor5/latest/features/title.html--known-issues">

### Known issues

The feature is not compatible with the [pagination](#ckeditor5/latest/features/pagination/pagination.html) feature.

<a id="ckeditor5/latest/features/title.html--related-features">

### Related features

CKEditor 5 has more features that can help you structure your document better:

* [Headings](#ckeditor5/latest/features/headings.html) – Divide your content into sections.
* [Block indentation](#ckeditor5/latest/features/indent.html) – Organize your content into visually separated blocks, indent crucial paragraphs, etc.
* [Editor placeholder](#ckeditor5/latest/features/editor-placeholder.html) – Set placeholder text to display when the content is empty. It helps users locate the editor in the application and prompts to input the content.

<a id="ckeditor5/latest/features/title.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-heading>.

<a id="ckeditor5/latest/features/undo-redo.html">source file: "ckeditor5/latest/features/undo-redo.html"</a>

## Undo/Redo

The undo feature lets you withdraw recent changes to your content as well as bring them back. You can also selectively revert past changes, not just the latest ones.

<a id="ckeditor5/latest/features/undo-redo.html--demo">

### Demo

Use the demo below to try out the undo and redo mechanism. Play around with the content. Try introducing some changes and then use the toolbar buttons to undo  or redo  them.

Alternatively, use the well-known keyboard shortcut Ctrl \+ Z (this would be Cmd \+ Z on Mac) for undo. For redo, you can use either Ctrl \+ Y or Ctrl \+ Shift \+ Z (respectively with Cmd on Mac).

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/undo-redo.html--additional-feature-information">

### Additional feature information

All operations of the undo feature are remembered and organized into batches that can later be easily undone or redone. Thanks to this approach, the feature can selectively revert past changes, not just the latest ones. This allows handling asynchronous actions such as image uploads without blocking the user from editing the document in the meantime.

The selective undo is heavily used in [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) environments. In such a scenario, a specific user should only be able to revert their changes, while keeping the changes made by other users intact (unless there is an editing conflict). By omitting some changes and going down the stack, it is possible to only revert selected changes.

The feature supports both toolbar buttons and [keyboard shortcuts](#ckeditor5/latest/features/accessibility.html--keyboard-shortcuts) for convenient and easy operation.

<a id="ckeditor5/latest/features/undo-redo.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/undo-redo.html--common-api">

### Common API

The [Undo](../api/module%5Fundo%5Fundo-Undo.html) plugin is a “glue” plugin that loads the [UndoEditing](../api/module%5Fundo%5Fundoediting-UndoEditing.html) engine and the [UndoUI](../api/module%5Fundo%5Fundoui-UndoUI.html) features.

The `UndoEditing` feature registers the following commands:

* The [UndoCommand](../api/module%5Fundo%5Fundocommand-UndoCommand.html) which can be programmatically called as `undo` and is used to retrieve editor history from a batch.  
```  
editor.execute( 'undo');  
```  
You can use it to retrieve changes from the latest batch, or from some previous batch (for example, changes made by a selected user in a collaborative environment):  
```  
editor.execute( 'undo', batchToUndo );  
```
* The [RedoCommand](../api/module%5Fundo%5Fredocommand-RedoCommand.html) is used to restore undo state from batch and is called as `redo`.  
```  
editor.execute( 'redo');  
```

The [UndoUI](../api/module%5Fundo%5Fundoui-UndoUI.html) feature introduces the `undo` and `redo` buttons to the editor toolbar.

<a id="ckeditor5/latest/features/undo-redo.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-undo>.

<a id="ckeditor5/latest/features/watchdog.html">source file: "ckeditor5/latest/features/watchdog.html"</a>

## Watchdog

The watchdog utility protects you from data loss in case the editor crashes. It saves your content just before the crash and creates a new instance of the editor with your content intact.

<a id="ckeditor5/latest/features/watchdog.html--additional-feature-information">

### Additional feature information

Every non-trivial piece of software has bugs. Despite our high-quality standards like 100% code coverage, regression testing, and manual tests before every release, CKEditor 5 is not free of bugs. Neither is the browser used by the user, your application in which CKEditor 5 is integrated, or any third-party add-ons that you used.

To limit the effect of an editor crash on the user experience, you can automatically restart the WYSIWYG editor with the content saved just before the crash.

The watchdog utility allows you to do exactly that. It ensures that an editor instance is running, despite a potential crash. It works by detecting that an editor crashed, destroying it, and automatically creating a new instance of that editor with the content of the previous editor.

Note that the most “dangerous” places in the CKEditor 5 API, like `editor.model.change()`, `editor.editing.view.change()` or emitters, are covered with checks and `try-catch` blocks that can detect unknown errors and restart the editor when they occur.

There are two available types of watchdogs:

* [Editor watchdog](#ckeditor5/latest/features/watchdog.html--editor-watchdog) – To be used with a single editor instance.
* [Context watchdog](#ckeditor5/latest/features/watchdog.html--context-watchdog) – To be used when your application uses the context.

<a id="ckeditor5/latest/features/watchdog.html--usage">

### Usage

<a id="ckeditor5/latest/features/watchdog.html--editor-watchdog">

#### Editor watchdog

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), change your `ClassicEditor.create()` call to `watchdog.create()` as follows:

In other words, your goal is to create a watchdog instance and make the watchdog create an instance of the editor you want to use. The watchdog will then create a new editor and if it ever crashes, restart it by creating a new editor.

<a id="ckeditor5/latest/features/watchdog.html--controlling-editor-creation-and-destruction">

##### Controlling editor creation and destruction

For more control over the creation and destruction of editor instances, you can use [EditorWatchdog#setCreator()](../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html#function-setCreator) and, if needed, the [EditorWatchdog#setDestructor()](../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html#function-setDestructor) methods:

```
// Create an editor watchdog.
const watchdog = new EditorWatchdog();

// Define a callback that will create an editor instance and return it.
watchdog.setCreator( ( editorConfig ) => {
    return ClassicEditor
        .create( editorConfig )
        .then( editor => {
            // Do something with the new editor instance.
            // ...
        } );
} );

// Do something before the editor is destroyed. Return a promise.
watchdog.setDestructor( editor => {
    // Do something before the editor is destroyed.
    // ...
    return editor
        .destroy()
        .then( () => {
            // Do something after the editor is destroyed.
            // ...
        } );
} );

// Create an editor instance and start watching it.
watchdog.create( editorConfig );

```

<a id="ckeditor5/latest/features/watchdog.html--editor-watchdog-api">

##### Editor watchdog API

Other useful [methods, properties and events](../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html):

```
watchdog.on( 'error', () => { console.log( 'Editor crashed.' ) } );
watchdog.on( 'restart', () => { console.log( 'Editor was restarted.' ) } );

// Destroy the watchdog and the current editor instance.
watchdog.destroy();

// The current editor instance.
watchdog.editor;

// The current state of the editor.
// The editor might be in one of the following states:
//
// * `initializing` - Before the first initialization, and after crashes, before the editor is ready.
// * `ready` - A state when the user can interact with the editor.
// * `crashed` - A state when an error occurs. It quickly changes to `initializing` or `crashedPermanently` depending on how many and how frequent errors have been caught recently.
// * `crashedPermanently` - A state when the watchdog stops reacting to errors and keeps the editor crashed.
// * `destroyed` - A state when the editor is manually destroyed by the user after calling `watchdog.destroy()`.
watchdog.state;

// Listen to state changes.

let prevState = watchdog.state;

watchdog.on( 'stateChange', () => {
    const currentState = watchdog.state;

    console.log( `State changed from ${ currentState } to ${ prevState }` );

    if ( currentState === 'crashedPermanently' ) {
        watchdog.editor.enableReadOnlyMode( 'crashed-editor' );
    }

    prevState = currentState;
} );

// An array of editor crash information.
watchdog.crashes.forEach( crashInfo => console.log( crashInfo ) );

```

<a id="ckeditor5/latest/features/watchdog.html--context-watchdog">

#### Context watchdog

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

To destroy one of the item instances, use [ContextWatchdog#remove](../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html#function-remove):

```
await watchdog.remove( [ 'editor1', 'editor2' ] );

// Or:
await watchdog.remove( 'editor1' );
await watchdog.remove( 'editor2' );

```

<a id="ckeditor5/latest/features/watchdog.html--context-watchdog-api">

##### Context watchdog API

The context watchdog feature provides the following API:

```
// Creating a watchdog that will use the context class and the watchdog configuration.
const watchdog = new ContextWatchdog( Context, watchdogConfig );

// Setting a custom creator for the context.
watchdog.setCreator( async config => {
    const context = await Context.create( config );

    // Do something when the context is initialized.
    // ...

    return context;
} );

// Setting a custom destructor for the context.
watchdog.setDestructor( async context => {

    // Do something before destroy.
    // ...

    await context.destroy();
} );

// Initializing the context watchdog with the context configuration.
await watchdog.create( contextConfig );

// Adding item configuration (or an array of item configurations).
await watchdog.add( {
    id: 'editor1',
    type: 'editor',
    config: editorConfig,
    creator: createEditor,
    destructor: destroyEditor,
} );

await watchdog.add( [
    {
        id: 'editor1',
        type: 'editor',
        config: editorConfig,
        creator: createEditor,
        destructor: destroyEditor,
    },
    // More configuration items.
    // ...
] );

// Remove and destroy a given item (or items).
await watchdog.remove( 'editor1' );

await watchdog.remove( [ 'editor1', 'editor2', ... ] );

// Getting the given item instance.
const editor1 = watchdog.getItem( 'editor1' );

// Getting the state of the given item.
const editor1State = watchdog.getItemState( 'editor1' );

// Getting the context state.
const contextState = watchdog.state;

// The `error` event is fired when the context watchdog catches a context-related error.
// Note that errors fired by items are not delegated to `ContextWatchdog#event:error`.
// See also `ContextWatchdog#event:itemError`.
watchdog.on( 'error', ( _, { error } ) => {

// The `restart` event is fired when the context is set back to the `ready` state (after it was in the `crashed` state).
// Similarly, this event is not thrown for internal item restarts.
watchdog.on( 'restart', () => {
    console.log( 'The context has been restarted.' );
} );

// The `itemError` event is fired when an error occurred in one of the added items.
watchdog.on( 'itemError', ( _, { error, itemId } ) => {
    console.log( `An error occurred in an item with the '${ itemId }' ID.` );
} );

// The `itemRestart` event is fired when an item is set back to the `ready` state (after it was in the `crashed` state).
watchdog.on( 'itemRestart', ( _, { itemId } ) => {
    console.log( 'An item with with the '${ itemId }' ID has been restarted.' );
} );

```

<a id="ckeditor5/latest/features/watchdog.html--configuration">

### Configuration

Both [EditorWatchdog](../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html#function-constructor) and [ContextWatchdog](../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html#function-constructor) constructors accept a [configuration object](../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) as the second argument with the following optional properties:

* `crashNumberLimit` – A threshold specifying the number of errors (defaults to `3`). After this limit is reached and the time between last errors is shorter than `minimumNonErrorTimePeriod`, the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
* `minimumNonErrorTimePeriod` – An average number of milliseconds between the last editor errors (defaults to 5000). When the period of time between errors is lower than that and the `crashNumberLimit` is also reached, the watchdog changes its state to `crashedPermanently` and it stops restarting the editor. This prevents an infinite restart loop.
* `saveInterval` – A minimum number of milliseconds between saving the editor data internally (defaults to 5000). Note that for large documents this might impact the editor’s performance.

```
const editorWatchdog = new EditorWatchdog( ClassicEditor, {
    minimumNonErrorTimePeriod: 2000,
    crashNumberLimit: 4,
    saveInterval: 1000
} );

```

<a id="ckeditor5/latest/features/watchdog.html--limitations">

### Limitations

The watchdog does not handle errors thrown during the editor or context initialization (for example, in `Editor.create()`) and editor destruction (for example, in `Editor#destroy()`). Errors thrown at these stages mean that there is a problem in the code integrating the editor with your application and such a problem cannot be fixed by restarting the editor.

<a id="ckeditor5/latest/features/word-count.html">source file: "ckeditor5/latest/features/word-count.html"</a>

## Word count and character count

The word count feature lets you track the number of words and characters in the editor. This helps you control the volume of your content and check the progress of your work.

<a id="ckeditor5/latest/features/word-count.html--demo">

### Demo

Add or remove some content and see how the counter below the editor changes in real time.

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/features/word-count.html--demo-word-count"> 

The example above was created by using the following HTML page structure:

```
<div id="editor">
    <p>Hello world.</p>
</div>
<div id="word-count"></div>

```

You can use the code below to set up the WYSIWYG editor with the word and character count features as in the example above.

```
ClassicEditor
    .create( {
        // Configuration details.
    } )
    .then( editor => {
        const wordCountPlugin = editor.plugins.get( 'WordCount' );
        const wordCountWrapper = document.getElementById( 'word-count' );

        wordCountWrapper.appendChild( wordCountPlugin.wordCountContainer );
    } );

```

<a id="ckeditor5/latest/features/word-count.html--installation">

### Installation

After [installing the editor](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), add the feature to your plugin list and toolbar configuration:

<a id="ckeditor5/latest/features/word-count.html--configuration">

### Configuration

The word count and character count feature is quite flexible and there are a few configuration options available.

<a id="ckeditor5/latest/features/word-count.html--configuring-the-container">

#### Configuring the container

There are two ways how you can inject the word count statistics into your page:

* By using the [WordCount#wordCountContainer](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-wordCountContainer) property as shown in the example above.
* By specifying where the word count feature should insert its container which can be done by using [config.wordCount.container](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-container).

The word count plugin renders its output as:

```
<div class="ck ck-word-count">
    <div class="ck-word-count__words">Words: %%</div>
    <div class="ck-word-count__characters">Characters: %%</div>
</div>

```

If you wish to render the statistics differently, see the [update event](#ckeditor5/latest/features/word-count.html--reacting-to-updates).

<a id="ckeditor5/latest/features/word-count.html--changing-the-output">

#### Changing the output

There are two configuration options available that change the output of the word count and character count features:

* If the [config.wordCount.displayWords](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-displayWords) option is set to `false`, the word counter will be hidden.
* If the [config.wordCount.displayCharacters](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-displayCharacters) option is set to `false`, the character counter will be hidden.

<a id="ckeditor5/latest/features/word-count.html--reacting-to-updates">

#### Reacting to updates

You can execute your custom callback every time content statistics change by defining [config.wordCount.onUpdate](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-onUpdate) in the editor configuration:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        wordCount: {
            onUpdate: stats => {
                // Prints the current content statistics.
                console.log( `Characters: ${ stats.characters }\nWords: ${ stats.words }` );
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

**Note**: For performance reasons, your callback will be throttled and may not be up–to–date. Use the [characters](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-characters) and [words](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-words) plugin properties to retrieve the precise numbers on demand.

Below you can play with a demo post editor with a soft 120-character limit. The progress chart underneath it indicates the number of characters in the content. The chart changes its color as the number nears or exceeds the limit. Type in the editor to see the feature in action. See the code used to create the demo listed below in this section.

```
const maxCharacters = 120;
const container = document.querySelector( '.demo-update' );
const progressCircle = document.querySelector( '.demo-update__chart__circle' );
const charactersBox = document.querySelector( '.demo-update__chart__characters' );
const wordsBox = document.querySelector( '.demo-update__words' );
const circleCircumference = Math.floor( 2 * Math.PI * progressCircle.getAttribute( 'r' ) );
const sendButton = document.querySelector( '.demo-update__send' );

BalloonEditor
    .create( {
        root: {
            element: document.querySelector( '#demo-update__editor' )
        },
        // Editor configuration.
        wordCount: {
            onUpdate: stats => {
                const charactersProgress = stats.characters / maxCharacters * circleCircumference;
                const isLimitExceeded = stats.characters > maxCharacters;
                const isCloseToLimit = !isLimitExceeded && stats.characters > maxCharacters * .8;
                const circleDashArray = Math.min( charactersProgress, circleCircumference );

                // Set the stroke of the circle to show how many characters were typed.
                progressCircle.setAttribute( 'stroke-dasharray', `${ circleDashArray },${ circleCircumference }` );

                // Display the number of characters in the progress chart. When the limit is exceeded,
                // display how many characters should be removed.
                if ( isLimitExceeded ) {
                    charactersBox.textContent = `-${ stats.characters - maxCharacters }`;
                } else {
                    charactersBox.textContent = stats.characters;
                }

                wordsBox.textContent = `Words in the post: ${ stats.words }`;

                // If the content length is close to the character limit, add a CSS class to warn the user.
                container.classList.toggle( 'demo-update__limit-close', isCloseToLimit );

                // If the character limit is exceeded, add a CSS class that makes the content's background red.
                container.classList.toggle( 'demo-update__limit-exceeded', isLimitExceeded );

                // If the character limit is exceeded, disable the send button.
                sendButton.toggleAttribute( 'disabled', isLimitExceeded );
            }
        }
    } );

```

Here is the HTML structure used to create the customized word and character count implementation above:

```
<style>
    .demo-update {
        border: 1px solid var(--ck-color-base-border);
        border-radius: var(--ck-border-radius);
        box-shadow: 2px 2px 0px hsla( 0, 0%, 0%, 0.1 );
        margin: 1.5em 0;
        padding: 1em;
    }

    .demo-update h3 {
        font-size: 18px;
        font-weight: bold;
        margin: 0 0 .5em;
        padding: 0;
    }

    .demo-update .ck.ck-editor__editable_inline {
        border: 1px solid hsla( 0, 0%, 0%, 0.15 );
        transition: background .5s ease-out;
        min-height: 6em;
        margin-bottom: 1em;
    }

    .demo-update__controls {
        display: flex;
        flex-direction: row;
        align-items: center;
    }

    .demo-update__chart {
        margin-right: 1em;
    }

    .demo-update__chart__circle {
        transform: rotate(-90deg);
        transform-origin: center;
    }

    .demo-update__chart__characters {
        font-size: 13px;
        font-weight: bold;
    }

    .demo-update__words {
        flex-grow: 1;
        opacity: .5;
    }

    .demo-update__limit-close .demo-update__chart__circle {
        stroke: hsl( 30, 100%, 52% );
    }

    .demo-update__limit-exceeded .ck.ck-editor__editable_inline {
        background: hsl( 0, 100%, 97% );
    }

    .demo-update__limit-exceeded .demo-update__chart__circle {
        stroke: hsl( 0, 100%, 52% );
    }

    .demo-update__limit-exceeded .demo-update__chart__characters {
        fill: hsl( 0, 100%, 52% );
    }
</style>

<div class="demo-update">
    <h3>Post editor with word count</h3>
    <div id="demo-update__editor">
        <p>Tourists frequently admit that <a href="https://en.wikipedia.org/wiki/Taj_Mahal">Taj Mahal</a> “simply cannot be described with words”.</p>
    </div>
    <div class="demo-update__controls">
        <span class="demo-update__words"></span>
        <svg class="demo-update__chart" viewbox="0 0 40 40" width="40" height="40" xmlns="http://www.w3.org/2000/svg">
            <circle stroke="hsl(0, 0%, 93%)" stroke-width="3" fill="none" cx="20" cy="20" r="17" />
            <circle class="demo-update__chart__circle" stroke="hsl(202, 92%, 59%)" stroke-width="3" stroke-dasharray="134,534" stroke-linecap="round" fill="none" cx="20" cy="20" r="17" />
            <text class="demo-update__chart__characters" x="50%" y="50%" dominant-baseline="central" text-anchor="middle"></text>
        </svg>
        <button type="button" class="demo-update__send">Send post</button>
    </div>
</div>

```

<a id="ckeditor5/latest/features/word-count.html--related-features">

### Related features

CKEditor 5 provides other productivity-boosting features that you may find helpful:

* [Proofreading, spelling and grammar checking](#ckeditor5/latest/features/spelling-and-grammar-checking.html) – Track and correct any possible errors as you type.
* [Autosave](#ckeditor5/latest/features/autosave.html) – Never lose your content by accident, stay safe and automatically save.
* [Autoformatting](#ckeditor5/latest/features/autoformat.html) – Employ Markdown syntax for a faster and more efficient editing process.
* [Automatic text transformation](#ckeditor5/latest/features/text-transformation.html) – Automatically turn predefined snippets into their improved forms using the autocorrect feature.

<a id="ckeditor5/latest/features/word-count.html--common-api">

### Common API

The [WordCount](../api/module%5Fword-count%5Fwordcount-WordCount.html) plugin provides:

* The [wordCountContainer](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-wordCountContainer) property. It returns a self-updating HTML element which is updated with the current number of words and characters in the editor. You can remove the “Words” or “Characters” counters with a proper configuration of the [config.wordCount.displayWords](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-displayWords) and [config.wordCount.displayCharacters](../api/module%5Fword-count%5Fwordcountconfig-WordCountConfig.html#member-displayCharacters) options.
* The [update event](../api/module%5Fword-count%5Fwordcount-WordCount.html#event-update), fired whenever the plugins update the number of counted words and characters. You can use it to run a custom callback function with updated values:  
```  
editor.plugins.get( 'WordCount' ).on( 'update', ( evt, stats ) => {  
    // Prints the current content statistics.  
    console.log( `Characters: ${ stats.characters }\nWords:      ${ stats.words }` );  
} );  
```  
Alternatively, you can use [config.wordCount.onUpdate](#ckeditor5/latest/features/word-count.html--reacting-to-updates) to register a similar callback via the editor configuration.

**Note**: For performance reasons, the `update` event is throttled so the statistics may not be up–to–date. Use the [characters](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-characters) and [words](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-words) plugin properties to retrieve the precise numbers on demand.
* The [characters](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-characters) and [words](../api/module%5Fword-count%5Fwordcount-WordCount.html#member-words) properties from which you can retrieve the stats at any moment.

<a id="ckeditor5/latest/features/word-count.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-word-count>.

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html">source file: "ckeditor5/latest/framework/architecture/core-editor-architecture.html"</a>

## Core editor architecture

The [@ckeditor/ckeditor5-core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core) package is relatively simple. It comes with just a handful of classes. The ones you need to know are presented below.

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html--editor-classes">

### Editor classes

The [Editor](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) class represents the base of the editor. It is the entry point of the application, gluing all other components. It provides a few properties that you need to know:

* [config](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-config) – The configuration object.
* [plugins](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-plugins) and [commands](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-commands) – The collection of loaded plugins and commands.
* [model](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-model) – The entry point to the [editor’s data model](#ckeditor5/latest/framework/architecture/editing-engine.html--model).
* [data](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-data) – The data controller. It controls how data is retrieved from the document and set inside it.
* [editing](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-editing) – The editing controller. It controls how the model is rendered to the user for editing.
* [keystrokes](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-keystrokes) – The keystroke handler. It allows to bind keystrokes to actions.

Besides that, the editor exposes a few of methods:

* [create()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) – The static `create()` method. Editor constructors are protected and you should create editors using this static method. It allows the initialization process to be asynchronous.
* [destroy()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-destroy) – Destroys the editor.
* [execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) – Executes the given command.
* [setData()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData) and [getData()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) – A way to retrieve the data from the editor and set the data in the editor. The data format is controlled by the [data controller’s data processor](../../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#member-processor). It does not need to be a string (it can be, for example, a JSON if you implement such a [data processor](../../api/module%5Fengine%5Fdataprocessor%5Fdataprocessor-DataProcessor.html)). See, for example, how to [produce Markdown output](#ckeditor5/latest/features/markdown.html).

For the full list of methods check the [API docs](../../api/index.html) of the editor class you use. Specific editor implementations may provide additional methods.

The [Editor](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) class is a base to implement your own editors. CKEditor 5 Framework comes with a few editor types (for example, [classic](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html), [inline](../../api/module%5Feditor-inline%5Finlineeditor-InlineEditor.html), [balloon](../../api/module%5Feditor-balloon%5Fballooneditor-BalloonEditor.html) and [decoupled](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html)) but you can freely implement editors which work and look completely different. The only requirement is that you implement the [Editor](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) interface.

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html--plugins">

### Plugins

Plugins are a way to introduce editor features. In CKEditor 5 even [typing](../../api/module%5Ftyping%5Ftyping-Typing.html) is a plugin. What is more, the [Typing](../../api/module%5Ftyping%5Ftyping-Typing.html) plugin depends on the [Input](../../api/module%5Ftyping%5Finput-Input.html) and [Delete](../../api/module%5Ftyping%5Fdelete-Delete.html) plugins which are responsible for handling the methods of inserting text and deleting content, respectively. At the same time, some plugins need to customize Backspace behavior in certain cases and handle it by themselves. This leaves the base plugins free of any non-generic knowledge.

Another important aspect of how existing CKEditor 5 plugins are implemented is the split into engine and UI parts. For example, the [BoldEditing](../../api/module%5Fbasic-styles%5Fbold%5Fboldediting-BoldEditing.html) plugin introduces the schema definition, mechanisms rendering `<strong>` tags, commands to apply and remove bold from text, while the [BoldUI](../../api/module%5Fbasic-styles%5Fbold%5Fboldui-BoldUI.html) plugin adds the UI of the feature (that is, the button). This feature split is meant to allow for greater reuse (one can take the engine part and implement their own UI for a feature) as well as for running CKEditor 5 on the server side. Finally, there is the [Bold](../../api/module%5Fbasic-styles%5Fbold-Bold.html) plugin that brings both plugins for a full experience.

The summary of this is that:

* Every feature is implemented or at least enabled by a plugin.
* Plugins are highly granular.
* Plugins know everything about the editor.
* Plugins should know as little about other plugins as possible.

These are the rules based on which the official plugins were implemented. When implementing your own plugins, if you do not plan to publish them, you can reduce this list to the first point.

After this lengthy introduction (which is aimed at making it easier for you to digest the existing plugins), the plugin API can be explained.

All plugins need to implement the [PluginInterface](../../api/module%5Fcore%5Fplugin-PluginInterface.html). The easiest way to do so is by inheriting from the [Plugin](../../api/module%5Fcore%5Fplugin-Plugin.html) class. The plugin initialization code should be located in the [init()](../../api/module%5Fcore%5Fplugin-PluginInterface.html#function-init) method (which can return a promise). If some piece of code needs to be executed after other plugins are initialized, you can put it in the [afterInit()](../../api/module%5Fcore%5Fplugin-PluginInterface.html#function-afterInit) method. The dependencies between plugins are implemented using the static [requires](../../api/module%5Fcore%5Fplugin-PluginStaticMembers.html#member-requires) property.

```
import MyDependency from 'some/other/plugin';

class MyPlugin extends Plugin {
    static get requires() {
        return [ MyDependency ];
    }

    init() {
        // Initialize your plugin here.

        this.editor; // The editor instance which loaded this plugin.
    }
}

```

You can see how to implement a simple plugin in the [step-by-step tutorial](#ckeditor5/latest/framework/tutorials/crash-course/editor.html).

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands">

### Commands

A command is a combination of an action (a callback) and a state (a set of properties). For instance, the `bold` command applies or removes the bold attribute from the selected text. If the text in which the selection is placed has bold applied already, the value of the command is `true`, `false` otherwise. If the `bold` command can be executed on the current selection, it is enabled. If not (because, for example, bold is not allowed in this place), it is disabled.

All commands need to inherit from the [Command](../../api/module%5Fcore%5Fcommand-Command.html) class. Commands need to be added to the editor’s [command collection](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-commands) so they can be executed by using the [Editor#execute()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute) method.

Take this example:

```
class MyCommand extends Command {
    execute( message ) {
        console.log( message );
    }
}

class MyPlugin extends Plugin {
    init() {
        const editor = this.editor;

        editor.commands.add( 'myCommand', new MyCommand( editor ) );
    }
}

```

Calling `editor.execute( 'myCommand', 'Foo!' )` will log `Foo!` to the console.

To see how state management of a typical command like `bold` is implemented, have a look at some pieces of the [AttributeCommand](../../api/module%5Fbasic-styles%5Fattributecommand-AttributeCommand.html) class on which `bold` is based.

The first thing to notice is the [refresh()](../../api/module%5Fcore%5Fcommand-Command.html#function-refresh) method:

```
refresh() {
    const doc = this.editor.document;

    this.value = doc.selection.hasAttribute( this.attributeKey );
    this.isEnabled = doc.schema.checkAttributeInSelection(
        doc.selection, this.attributeKey
    );
}

```

This method is called automatically (by the command itself) when [any changes are applied to the model](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change). This means that the command automatically refreshes its own state when anything changes in the editor.

The important thing about commands is that every change in their state as well as calling the `execute()` method fire events. Some examples of these are [#set:value](../../api/module%5Fcore%5Fcommand-Command.html#event-set:%7Bproperty%7D) and [#change:value](../../api/module%5Fcore%5Fcommand-Command.html#event-change:%7Bproperty%7D) when you change the `#value` property and [#execute](../../api/module%5Fcore%5Fcommand-Command.html#event-execute) when you execute the command.

These events make it possible to control the command from the outside. For instance, if you want to block specific commands when some condition is true (for example, according to your application logic, they should be temporarily unavailable) and there is no other, cleaner way to do that, you can disable the command using the built-in helper [forceDisabled()](../../api/module%5Fcore%5Fcommand-Command.html#function-forceDisabled) (and re-enable it with [clearForceDisabled()](../../api/module%5Fcore%5Fcommand-Command.html#function-clearForceDisabled)):

```
// Disabling the command.
const boldCommand = editor.commands.get( 'bold' );
boldCommand.forceDisabled( 'MyFeature' );

// Enabling the command again.
boldCommand.clearForceDisabled( 'MyFeature' );

```

The command will remain disabled until `clearForceDisabled( 'MyFeature' )` is called and no other feature keeps it disabled, regardless of how many times `someCommand.refresh()` is called.

By default, editor commands are blocked when the editor is in the [read-only](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) mode. However, if your command does not change the editor data and you want it to stay enabled in the read-only mode, you can set the [affectsData](../../api/module%5Fcore%5Fcommand-Command.html#member-affectsData) flag to `false`:

```
class MyAlwaysEnabledCommand extends Command {
    constructor( editor ) {
        super( editor );

        // This command will remain enabled even when the editor is read-only.
        this.affectsData = false;
    }
}

```

The [affectsData](../../api/module%5Fcore%5Fcommand-Command.html#member-affectsData) flag will also affect the command in [other editor modes](#ckeditor5/latest/features/read-only.html--related-features) that restrict user write permissions.

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html--event-system-and-observables">

### Event system and observables

CKEditor 5 has an event-based architecture so you can find [Emitter](../../api/module%5Futils%5Femittermixin-Emitter.html) and [Observable](../../api/module%5Futils%5Fobservablemixin-Observable.html) mixed all over the place. Both mechanisms allow for decoupling the code and make it extensible.

Most of the classes that have already been mentioned are either emitters or observables (observable is an emitter, too). An emitter can emit (fire) events as well as listen to them.

```
class MyPlugin extends Plugin {
    init() {
        // Make MyPlugin listen to someCommand#execute.
        this.listenTo( someCommand, 'execute', () => {
            console.log( 'someCommand was executed' );
        } );

        // Make MyPlugin listen to someOtherCommand#execute and block it.
        // You listen with a high priority to block the event before
        // someOtherCommand's execute() method is called.
        this.listenTo( someOtherCommand, 'execute', evt => {
            evt.stop();
        }, { priority: 'high' } );
    }

    // Inherited from Plugin:
    destroy() {
        // Removes all listeners added with this.listenTo();
        this.stopListening();
    }
}

```

The second listener to `'execute'` shows one of the common practices in CKEditor 5 code. Basically, the default action of `'execute'` (which is calling the `execute()` method) is registered as a listener to that event with a default priority. Thanks to that, by listening to the event using `'low'` or `'high'` priorities you can execute some code before or after `execute()` is really called. If you stop the event, then the `execute()` method will not be called at all. In this particular case, the [Command#execute()](../../api/module%5Fcore%5Fcommand-Command.html#function-execute) method was decorated with the event using the [ObservableMixin#decorate()](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-decorate) function:

```
import { ObservableMixin, mix } from 'ckeditor5';

class Command {
    constructor() {
        this.decorate( 'execute' );
    }

    // Will now fire the #execute event automatically.
    execute() {}
}

// Mix ObservableMixin into Command.
mix( Command, ObservableMixin );

```

Besides decorating methods with events, observables allow to observe their chosen properties. For instance, the `Command` class makes its `#value` and `#isEnabled` observable by calling [set()](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-set:KEY%5FVALUE):

```
class Command {
    constructor() {
        this.set( 'value', undefined );
        this.set( 'isEnabled', undefined );
    }
}

mix( Command, ObservableMixin );

const command = new Command();

command.on( 'change:value', ( evt, propertyName, newValue, oldValue ) => {
    console.log(
        `${ propertyName } has changed from ${ oldValue } to ${ newValue }`
    );
} )

command.value = true; // -> 'value has changed from undefined to true'

```

Observables have one more feature which is widely used by the editor (especially in the UI library) – the ability to bind the value of one object’s property to the value of some other property or properties (of one or more objects). This, of course, can also be processed by callbacks.

Assuming that `target` and `source` are observables and that used properties are observable:

```
target.bind( 'foo' ).to( source );

source.foo = 1;
target.foo; // -> 1

// Or:
target.bind( 'foo' ).to( source, 'bar' );

source.bar = 1;
target.foo; // -> 1

```

You can also find more about data bindings in the user interface in the [UI library architecture](#ckeditor5/latest/framework/architecture/ui-library.html) guide.

<a id="ckeditor5/latest/framework/architecture/core-editor-architecture.html--read-next">

### Read next

Once you have learned how to create plugins and commands you can read how to implement real editing features in the [Editing engine](#ckeditor5/latest/framework/architecture/editing-engine.html) guide.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html">source file: "ckeditor5/latest/framework/architecture/editing-engine.html"</a>

## Editing engine

The [@ckeditor/ckeditor5-engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine) is the largest package in CKEditor 5\. This guide introduces the main architecture and key concepts. More detailed guides are available for specific topics.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--overview">

### Overview

The editing engine uses a Model-View-Controller (MVC) architecture. While the engine does not enforce a specific structure, most implementations follow this pattern:

The architecture has three layers: **model**, **controller**, and **view**. There is one **model document** that gets **converted** into two separate views: the **editing view** and the **data view**. These views represent different things:

* The editing view shows the content users see in the browser and interact with.
* The data view handles the editor’s input and output data in a format the data processor understands.

Both views use virtual DOM structures (custom, DOM-like structures) that converters and features work with. These structures are then **rendered** to the actual DOM.

The deep blue blocks in the diagram represent code from editor features (plugins). Features control what changes happen to the model, how those changes convert to the view, and how the model updates based on events.

Let’s explore each layer separately.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--model">

### Model

The model is a DOM-like tree structure consisting of [elements](../../api/module%5Fengine%5Fmodel%5Felement-ModelElement.html) and [text nodes](../../api/module%5Fengine%5Fmodel%5Ftext-ModelText.html). Unlike the actual DOM, both elements and text nodes in the model can have attributes.

Like the DOM, the model structure lives inside a [document](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html) that contains [root elements](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#member-roots). The model and view can both have multiple roots. The document also holds the [selection](../../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html) and the [history of its changes](../../api/module%5Fengine%5Fmodel%5Fhistory-History.html).

The document, its [schema](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html), and [document markers](../../api/module%5Fengine%5Fmodel%5Fmarkercollection-MarkerCollection.html) are properties of the [Model](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html) class. You can access an instance of the `Model` class through [editor.model](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-model). Besides holding these properties, the model provides the API for changing the document and its markers.

```
editor.model;                       // -> The data model
editor.model.document;              // -> The document
editor.model.document.getRoot();    // -> The document's root
editor.model.document.selection;    // -> The document's selection
editor.model.schema;                // -> The model's schema

```

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-model">

#### Changing the model

You can only change the document structure, selection, and create elements using the [model writer](../../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html). Access the writer instance in the [change()](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-change) and the [enqueueChange()](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-enqueueChange:DEFAULT%5FBATCH) blocks.

```
// Inserts text "foo" at the selection position
editor.model.change( writer => {
    writer.insertText( 'foo', editor.model.document.selection.getFirstPosition() );
} );

// Apply bold to the entire selection
editor.model.change( writer => {
    for ( const range of editor.model.document.selection.getRanges() ) {
        writer.setAttribute( 'bold', true, range );
    }
} );

```

All changes within a single `change()` block combine into one undo step (added to a single [batch](../../api/module%5Fengine%5Fmodel%5Fbatch-Batch.html)). When you nest `change()` blocks, all changes go to the outermost block’s batch. For example, this code creates a single undo step:

```
editor.model.change( writer => {
    writer.insertText( 'foo', paragraph, 'end' ); // foo

    editor.model.change( writer => {
        writer.insertText( 'bar', paragraph, 'end' ); // foobar
    } );

    writer.insertText( 'bom', paragraph, 'end' ); // foobarbom
} );

```

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--text-attributes">

#### Text attributes

Text styles like “bold” and “italic” are stored in the model as text attributes, not as elements (think of them like element attributes). This DOM structure:

```
<p>
    "Foo "
    <strong>
        "bar"
    </strong>
</p>

```

translates to this model structure:

```
<paragraph>
    "Foo "  // text node
    "bar"   // text node with bold=true attribute
</paragraph>

```

This representation of inline text styling significantly reduces the complexity of algorithms working with the model. For instance, with this DOM structure:

```
<p>
    "Foo "
    <strong>
        "bar"
    </strong>
</p>

```

If you have a selection before the letter “b” (`"Foo ^bar"`), is this position inside or outside `<strong>`? With [native DOM Selection](https://developer.mozilla.org/en-US/docs/Web/API/Selection), you could get both positions – one anchored in `<p>` and another in `<strong>`. In CKEditor 5, this position translates exactly to `"Foo ^bar"`.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--selection-attributes">

#### Selection attributes

How does CKEditor 5 know that the selection should “be bold” in the case described above? It matters because it determines whether typed text will be bold.

The selection also [has attributes](../../api/module%5Fengine%5Fmodel%5Fselection-ModelSelection.html#function-setAttribute). If the selection is at `"Foo ^bar"` with the attribute `bold=true`, you know the user will type bold text.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--indexes-and-offsets">

#### Indexes and offsets

In the previous example, inside `<paragraph>` there are two text nodes: `"Foo "` and `"bar"`. If you know how [native DOM Ranges](https://developer.mozilla.org/en-US/docs/Web/API/Range) work, you might ask: “If the selection is at the boundary of two text nodes, is it anchored in the left one, the right one, or in the containing element?”

It is another problem with DOM APIs. Positions outside and inside some element can be visually identical, and they can be anchored inside or outside a text node (if the position is at a text node boundary). It creates complications when implementing editing algorithms.

To avoid these problems and enable real collaborative editing, CKEditor 5 uses **indexes** and **offsets**. Indexes relate to nodes (elements and text nodes) while offsets relate to positions. For example, in this structure:

```
<paragraph>
    "Foo "
    <imageInline></imageInline>
    "bar"
</paragraph>

```

* The `"Foo "` text node is at index `0` in its parent
* `<imageInline>` is at index `1`
* `"bar"` is at index `2`

Meanwhile, offset `x` in `<paragraph>` translates to:

| Offset | Position                                                   | Node          |
| ------ | ---------------------------------------------------------- | ------------- |
| 0      | <paragraph>^Foo <imageInline></imageInline>bar</paragraph> | "Foo "        |
| 1      | <paragraph>F^oo <imageInline></imageInline>bar</paragraph> | "Foo "        |
| 4      | <paragraph>Foo ^<imageInline></imageInline>bar</paragraph> | <imageInline> |
| 6      | <paragraph>Foo <imageInline></imageInline>b^ar</paragraph> | "bar"         |

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--positions-ranges-and-selections">

#### Positions, ranges and selections

The engine defines three levels of classes that work with offsets:

* A [ModelPosition](../../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html) instance contains an [array of offsets](../../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html#member-path) (which is called a “path”). See the [Position#path API documentation](../../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html#member-path) for examples of how paths work.
* A [ModelRange](../../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html) contains two positions: [start](../../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html#member-start) and [end](../../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html#member-end).
* Finally, there is the [ModelSelection](../../api/module%5Fengine%5Fmodel%5Fselection-ModelSelection.html) class, which represents a selection in the model. A `ModelSelection` can contain one or more ranges, selection attributes, and information about its direction (whether it was made from left to right or right to left). You can create and modify as many `ModelSelection` instances as you need. In addition, a single [ModelDocumentSelection](../../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html) instance always represents the user’s actual selection in the document. This `ModelDocumentSelection` can only be changed using the [model writer](../../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html) and is automatically kept in sync when the document structure changes.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--markers">

#### Markers

Markers are a special type of range with these characteristics:

* Managed by [MarkerCollection](../../api/module%5Fengine%5Fmodel%5Fmarkercollection-MarkerCollection.html).
* Can only be created and changed through the [model writer](../../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html).
* Can be synchronized over the network with collaborating clients.
* Automatically update when the document structure changes.
* Can be converted to the editing view to display in the editor (as [highlights](../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-markerToHighlight) or [elements](../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-markerToElement)).
* Can be converted [converted to the data view](../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-markerToData) to store with the document data.
* Can be [loaded with the document data](../../api/module%5Fengine%5Fconversion%5Fupcasthelpers-UpcastHelpers.html#function-dataToMarker).

Markers are perfect for storing and maintaining additional data related to document portions, such as comments or other users’ selections.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--schema">

#### Schema

The [model’s schema](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html) defines several aspects of the model structure:

* **Where nodes are allowed or disallowed,** for example, a `paragraph` is allowed in `$root`, but not in `heading1`.
* **What attributes are allowed for a node,** for example, an `image` can have `src` and `alt` attributes.
* **Additional semantics of model nodes,** for example, an `image` is of the “object” type and a `paragraph` is of the “block” type.

The schema can also define specifically disallowed children and attributes. It is useful when nodes inherit properties from other nodes but need to exclude certain things:

* **Disallowed nodes in certain places,** for example, a custom `specialParagraph` element inherits all properties from `paragraph` but disallows `imageInline`.
* **Disallowed attributes on a node,** for example, a custom `specialPurposeHeading` element inherits attributes from `heading2` but does not allow the `alignment` attribute.

Features and the engine use this information to make processing decisions. The schema affects:

* What happens with pasted content and what gets filtered out (note: for pasting, conversion is also important. HTML elements and attributes not converted by registered converters are filtered out before becoming model nodes, so the schema does not apply to them).
* Which elements the heading feature can be applied to (which blocks can become headings and which elements are blocks).
* Which elements can be wrapped with a block quote.
* Whether the bold button is enabled when the selection is in a heading (and whether text in the heading can be made bold).
* Where the selection can be placed (only in text nodes and on object elements).
* And more.

By default, editor plugins configure the schema. We recommend that every editor feature come with rules that enable and pre-configure it. It ensures plugin users can enable features without worrying about reconfiguring their schema.

Access the schema instance at [editor.model.schema](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#member-schema). For an in-depth guide on using the schema API, see the [Schema Deep Dive guide](#ckeditor5/latest/framework/deep-dive/schema.html).

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--view">

### View

Let’s look at the editing engine’s architecture again:

We have discussed the topmost layer – the model. The model layer creates an abstraction over the data. Its format was designed to allow storing and modifying data conveniently while enabling complex features. Most features operate on the model (reading from it and changing it).

The view, on the other hand, is an abstract representation of the DOM structure that should be presented to the user for editing and that should (in most cases) represent the editor’s input and output (the data returned by `editor.getData()`, data set by `editor.setData()`, pasted content, etc.).

This means:

* The view is another custom structure.
* It resembles the DOM. While the model’s tree structure only slightly resembled the DOM (for example, by introducing text attributes), the view is much closer. In other words, it is a **virtual DOM.**
* There are two “pipelines”: the [**editing pipeline**](#ckeditor5/latest/framework/architecture/editing-engine.html--editing-pipeline) (also called the “editing view”) and the [**data pipeline**](#ckeditor5/latest/framework/architecture/editing-engine.html--data-pipeline) (the “data view”). Think of them as two separate views of one model. The editing pipeline renders and handles the DOM that users see and can edit. The data pipeline is used when you call the `editor.getData()`, `editor.setData()`, or paste content into the editor.
* The views are rendered to the DOM by the [ViewRenderer](../../api/module%5Fengine%5Fview%5Frenderer-ViewRenderer.html), which handles all the quirks required to tame `contentEditable` used in the editing pipeline.

The two views are visible in the API:

```
editor.editing;                 // The editing pipeline (EditingController)
editor.editing.view;            // The editing view's controller
editor.editing.view.document;   // The editing view's document
editor.data;                    // The data pipeline (DataController)

```

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--element-types-and-custom-data">

#### Element types and custom data

The structure of the view closely resembles that of the DOM. While the semantics of HTML are defined by its specification, the view structure is “DTD-free.” To provide additional context and better express content semantics, the view defines six element types ([ViewContainerElement](../../api/module%5Fengine%5Fview%5Fcontainerelement-ViewContainerElement.html), [ViewAttributeElement](../../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html), [ViewEmptyElement](../../api/module%5Fengine%5Fview%5Femptyelement-ViewEmptyElement.html), [ViewRawElement](../../api/module%5Fengine%5Fview%5Frawelement-ViewRawElement.html), [ViewUIElement](../../api/module%5Fengine%5Fview%5Fuielement-ViewUIElement.html), and [ViewEditableElement](../../api/module%5Fengine%5Fview%5Feditableelement-ViewEditableElement.html)) as well as [“custom properties”](../../api/module%5Fengine%5Fview%5Felement-ViewElement.html#function-getCustomProperty) (custom, non-rendered properties on elements). Editor features provide this additional information, and the [ViewRenderer](../../api/module%5Fengine%5Fview%5Frenderer-ViewRenderer.html) and [converters](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion) then use it.

The element types are:

* **Container element:** Elements that build the content structure. Used for block elements like `<p>`, `<h1>`, `<blockQuote>`, `<li>`, etc.
* **Attribute element:** Most model text attributes convert to view attribute elements. Used mostly for inline styling elements like `<strong>`, `<i>`, `<a>`, `<code>`. The view writer flattens similar attribute elements. For example, `<a href="..."><a class="bar">x</a></a>` automatically optimizes to `<a href="..." class="bar">x</a>`.
* **Empty element:** Elements that must not have child nodes, like `<img>`.
* **UI element:** Elements that are not part of the “data” but need to be “inlined” in the content. The selection ignores them (jumps over them), as does the view writer in general. The contents and events from these elements are also filtered out.
* **Raw element:** Elements that work as data containers (“wrappers,” “sandboxes”), but their children are transparent to the editor. Useful to render non-standard data, but the editor should not be concerned with what it is or how it works. Users cannot place the selection inside a raw element, split it into smaller chunks, or modify its content directly.
* **Editable element:** Elements used as “nested editable elements” of non-editable content fragments. For example, a caption in an image widget, where the `<figure>` wrapping the image is not editable (it is a widget) and the `<figcaption>` inside it is an editable element.

Additionally, you can define [custom properties](../../api/module%5Fengine%5Fview%5Felement-ViewElement.html#function-getCustomProperty) to store information like:

* Whether an element is a widget (added by [toWidget()](../../api/module%5Fwidget%5Futils.html#function-toWidget)).
* How an element should be marked when a [marker](#ckeditor5/latest/framework/architecture/editing-engine.html--markers) highlights it.
* Whether an element belongs to a particular feature – if it is a link, progress bar, caption, etc.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--non-semantic-views">

##### Non-semantic views

Not all view trees need to (or can) be built with semantic element types. View structures generated directly from input data (for instance, pasted HTML or with `editor.setData()`) consist only of [base element](../../api/module%5Fengine%5Fview%5Felement-ViewElement.html) instances. These view structures are (usually) converted to model structures and then converted back to view structures for editing or data retrieval, at which point they become semantic views again.

The additional information in semantic views and the special operations feature developers want to perform on those trees (compared to simple tree operations on non-semantic views) means both structures need to be [modified by different tools](#ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-view).

We’ll explain [conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion) later in this guide. For now, just know that there are semantic views for rendering and data retrieval, and non-semantic views for data input.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-view">

#### Changing the view

Do not change the view manually unless you know exactly what you are doing. If the view needs to change, in most cases the model should change first. Then, the changes you apply to the model are converted to the view by specific converters (see [conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion) for more details).

Sometimes you have to change the view manually if the model does not reflect the cause of the change. For example, the model does not store information about focus, which is a [property of the view](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#member-isFocused). When the focus changes, and you want to represent that in an element’s class, you need to change that class manually.

For that, like in the model, use the `change()` block (of the view) where you will have access to the view downcast writer.

```
editor.editing.view.change( writer => {
    writer.insert( position, writer.createText( 'foo' ) );
} );

```

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--positions">

#### Positions

Like [in the model](https://github.com/ckeditor/ckeditor5/pull/19651#positions-ranges-and-selections), there are 3 levels of classes in the view that describe points in the view structure: **positions**, **ranges**, and **selections**.

* A **position** is a single point in the document.
* A **range** consists of two positions (start and end).
* A **selection** consists of one or more ranges with a direction (whether it was made from left to right or right to left).

A view range is similar to its [DOM counterpart](https://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges.html). View positions are represented by a parent and an offset in that parent. This means, unlike model offsets, view offsets describe:

* Points between child nodes of the position’s parent if it is an element.
* Or points between characters of a text node if the position’s parent is a text node.

Therefore, view offsets work more like model indexes than model offsets.

| Parent | Offset | Position                  |
| ------ | ------ | ------------------------- |
| <p>    | 0      | <p>^Foo<img></img>bar</p> |
| <p>    | 1      | <p>Foo^<img></img>bar</p> |
| <p>    | 2      | <p>Foo<img></img>^bar</p> |
| <img>  | 0      | <p>Foo<img>^</img>bar</p> |
| Foo    | 1      | <p>F^oo<img></img>bar</p> |
| Foo    | 3      | <p>Foo^<img></img>bar</p> |

As you can see, two of these positions represent what you might consider the same point in the document:

* `{ parent: paragraphElement, offset: 1 }`
* `{ parent: fooTextNode, offset: 3 }`

Some browsers (Safari, Chrome, and Opera) consider them identical when used in a selection and often normalize the first position (anchored in an element) to a position anchored in a text node (the second position). Do not be surprised if the view selection is not directly where you expect it to be. The good news is that the CKEditor 5 renderer can tell that two positions are identical and avoids unnecessarily re-rendering the DOM selection.

The inconvenient representation of DOM positions is yet another reason to think about and work with model positions.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--observers">

#### Observers

To create a safer and more useful abstraction over native DOM events, the view implements the concept of [observers](../../api/module%5Fengine%5Fview%5Fobserver%5Fobserver-Observer.html). It improves the editor’s testability and simplifies listeners added by editor features by transforming native events into a more useful form.

An observer listens to one or more DOM events, does preliminary processing, and then fires a custom event on the [view document](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html). An observer creates an abstraction not only of the event itself, but also of its data. Ideally, an event’s consumer should not have any access to the native DOM.

By default, the view adds these observers:

* [MutationObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Fmutationobserver-MutationObserver.html)
* [SelectionObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Fselectionobserver-SelectionObserver.html)
* [FocusObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Ffocusobserver-FocusObserver.html)
* [KeyObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Fkeyobserver-KeyObserver.html)
* [FakeSelectionObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Ffakeselectionobserver-FakeSelectionObserver.html)
* [CompositionObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Fcompositionobserver-CompositionObserver.html)
* [ArrowKeysObserver](../../api/module%5Fengine%5Fview%5Fobserver%5Farrowkeysobserver-ArrowKeysObserver.html)

Additionally, some features add their own observers. For instance, the [clipboard feature](../../api/module%5Fclipboard%5Fclipboard-Clipboard.html) adds [ClipboardObserver](../../api/module%5Fclipboard%5Fclipboardobserver-ClipboardObserver.html).

You can add your own observer (which should be a subclass of [Observer](../../api/module%5Fengine%5Fview%5Fobserver%5Fobserver-Observer.html)) by using the [view.addObserver()](../../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-addObserver) method. Check the [code of existing observers](https://github.com/ckeditor/ckeditor5-engine/tree/master/src/view/observer) to learn how to write them.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--conversion">

### Conversion

We have talked about the model and the view as two completely independent subsystems. It is time to connect them. The three main situations where these two layers meet are:

| Conversion name                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Data upcasting](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html)                            | **Loading the data to the editor.** First, a [DataProcessor](../../api/module%5Fengine%5Fdataprocessor%5Fdataprocessor-DataProcessor.html) processes the data (for example, an HTML string) into a view [ViewDocumentFragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html). Then, the conversion process turns this view document fragment into a model [document fragment](../../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html). Finally, the editor inserts this content into the model document’s [root](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#member-roots). |
| [Data downcasting](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html--downcast-pipelines)    | **Retrieving the data from the editor.** First, the editor converts the content of the model’s root to a view document fragment. Then, a data processor transforms this view document fragment into the target data format.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [Editing downcasting](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html--downcast-pipelines) | **Rendering the editor content to the user for editing.** This process runs throughout the editor’s lifetime after initialization. First, once _data upcasting_ finishes, the editor converts the model’s root to the view’s root. Afterward, the editor renders this view root to the user inside the editor’s contentEditable DOM element (also called “the editable element”). Whenever the model changes, the editor converts those changes to the view. If necessary (for example, if the DOM differs from the view), the editor re-renders the view to the DOM.                                                                                     |

Let’s look at the diagram of the engine’s MVC architecture and see where each conversion process happens:

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--data-pipeline">

#### Data pipeline

[**Data upcasting**](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html) is a process that starts in the bottom-left corner of the diagram (in the view layer), passes from the data view through a converter in the controller layer to the model document in the top. As you can see, it goes from bottom to top, hence “upcasting.” Furthermore, it is handled by the data pipeline, hence “data upcasting.” Note that data upcasting is also used to process pasted content (which is similar to loading data).

[**Data downcasting**](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html--downcast-pipelines) is the opposite process to data upcasting. It starts at the top and goes down to the bottom-left corner. Again, the conversion process name matches the direction and the pipeline.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--editing-pipeline">

#### Editing pipeline

[**Editing downcasting**](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html--downcast-pipelines) is a bit different from the other two processes:

* It takes place in the “editing pipeline” (the right branch of the diagram).
* It does not have a counterpart. Editing upcasting does not exist because editor features listen to [view events](#ckeditor5/latest/framework/architecture/editing-engine.html--observers), analyze what has happened, and apply necessary changes to the model whenever users perform actions. Therefore, this process does not involve conversion.
* Unlike [DataController](../../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html) (which handles the _data pipeline_), [EditingController](../../api/module%5Fengine%5Fcontroller%5Feditingcontroller-EditingController.html) maintains a single instance of the [ViewDocument](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html) for its entire life. Every change in the model is converted to changes in that view, so changes in that view can then be rendered to the DOM (if needed – that is, if the DOM actually differs from the view at this stage).

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--more-information">

#### More information

You can find a more in-depth introduction with examples in the [dedicated conversion guide](#ckeditor5/latest/framework/deep-dive/conversion/intro.html).

For additional information, you can also check out the [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--defining-converters) and [Implementing an inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--defining-converters) tutorials.

<a id="ckeditor5/latest/framework/architecture/editing-engine.html--read-next">

### Read next

Once you have learned how to implement editing features, it is time to add a UI for them. You can read about the CKEditor 5 standard UI framework and UI library in the UI library guide.

<a id="ckeditor5/latest/framework/architecture/intro.html">source file: "ckeditor5/latest/framework/architecture/intro.html"</a>

## Introduction to CKEditor 5 architecture

This guide introduces the main pillars of the CKEditor 5 architecture.

<a id="ckeditor5/latest/framework/architecture/intro.html--basic-ckeditor-5-architecture">

### Basic CKEditor 5 architecture

<a id="ckeditor5/latest/framework/architecture/intro.html--design">

#### Design

The framework was designed to be a highly flexible and universal platform for creating custom rich-text editing solutions. At the same time, it meets several goals that make implementing features as easy a task as possible.

* **Plugin-based architecture.** Everything is a plugin – even such crucial features as support for typing or `<p>` elements. You can remove plugins or replace them with your own implementations to achieve fully customized results.
* **Schema-less core.** The core makes minimal assumptions and can be controlled through the schema. This leaves all decisions to plugins and hence to you.
* **Collaboration-ready.** Or rather, real-time collaboration is **ready for you to use**! The editor implements [Operational Transformation](https://en.wikipedia.org/wiki/Operational%5Ftransformation) for the tree-structured model as well as many other mechanisms which were required to create a seamless collaborative UX. Additionally, we provide cloud infrastructure and plugins enabling real-time collaborative editing in your application! [Check the collaboration demo](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html).
* **Custom data model.** The editing engine implements a tree-structured custom data model, designed to fit multiple requirements such as enabling real-time collaboration and complex editing features (like tables or nested blocks).
* **Virtual DOM.** The editing engine features a custom, editing-oriented virtual DOM implementation that aims to hide browser quirks from your sight. **No more `contentEditable` nightmares!**
* **TypeScript.** The project is written in TypeScript and provides native type definitions. This helps create better, more reliable code that is easier to understand and maintain.
* **Granular, reusable features.** Features are implemented in a granular way. This allows for reusing and recomposing them which, in turn, makes it possible to customize and extend the editor. For instance, the [image feature](#ckeditor5/latest/features/images/images-overview.html) consists of over 10 plugins at the moment.
* **Extensibility.** The entire editor architecture was designed for maximum flexibility. The code is event-based and highly decoupled, allowing you to plug in or replace selected pieces. Features do not directly depend on one another and communicate in standardized ways.
* **A beautiful UI.** Text editing is not only about typing – your users will need a UI to create links or manage images. We believe that a proper UX needs to be carefully designed and we did not skip this part. Having second thoughts about the proposed UI? No problem at all! You can always create your custom interface for CKEditor 5 thanks to its decoupled UI.
* **Quality.** All official packages have extensive test suites (100% code coverage is merely a step to that). All code has extensive [API documentation](../../api/index.html).
* **Minimal configuration.** To avoid bloat, features have minimal configuration. Deeper changes in their behavior can be done by recomposing them with custom features.
* **8+ years of support.** It is not yet another framework to be gone next year or a hyped proof-of-concept to fail in a real-life scenario. We have over 20 years of experience in creating rich-text editors and continue working day in and day out on improving your future-proof rich-text editor of choice.

<a id="ckeditor5/latest/framework/architecture/intro.html--framework-structure">

#### Framework structure

The framework is made of several [npm packages](https://npmjs.com). Each package is available in the [/packages](https://github.com/ckeditor/ckeditor5/tree/master/packages) directory of the CKEditor 5 GitHub repository.

There are a few groups of packages:

* Core libraries – A set of packages which are the root of the framework.
* Editors – Packages that implement various types of editors.
* Features – Packages that implement end-user features.
* Themes – Packages that implement editor themes.

<a id="ckeditor5/latest/framework/architecture/intro.html--main-components">

### Main components

CKEditor 5 Framework comes with its 3 main pillars:

* **[Core editor architecture](#ckeditor5/latest/framework/architecture/core-editor-architecture.html)**  
The core editor architecture is implemented by the [@ckeditor/ckeditor5-core](../../api/core.html) package. It consists of some core classes and interfaces that glue everything together.  
The main purpose of the core editor architecture is to lay the groundwork for implementing editor features. Therefore, it introduces concepts such as [plugins](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--plugins) and [commands](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) which simplify and standardize the way of implementing features.
* **[Editing engine](#ckeditor5/latest/framework/architecture/editing-engine.html)**  
The editing engine is implemented by the [@ckeditor/ckeditor5-engine](../../api/engine.html) package. It is the biggest and by far the most complex piece of the framework, implementing the custom data model, the view layer, conversion mechanisms, the rendering engine responsible for [taming contentEditable](https://medium.com/content-uneditable/contenteditable-the-good-the-bad-and-the-ugly-261a38555e9c) and a lot more.
* **[UI library](#ckeditor5/latest/framework/architecture/ui-library.html)**  
The standard UI library is implemented by the [@ckeditor/ckeditor5-ui](../../api/ui.html) package. It contains a simple MVC implementation whose main goal is to best fit the CKEditor 5 needs. Furthermore, it introduces basic UI components to be used by editor features.

<a id="ckeditor5/latest/framework/architecture/plugins.html">source file: "ckeditor5/latest/framework/architecture/plugins.html"</a>

## Plugins in CKEditor 5

Features in CKEditor are introduced by plugins. In fact, without plugins, CKEditor 5 is an empty API with no use. Plugins provided by the CKEditor core team are available in [npm](https://www.npmjs.com/search?q=ckeditor5) (and [GitHub](https://github.com/ckeditor?utf8=%E2%9C%93&q=ckeditor5&type=&language=), too) in the form of npm packages. A package may contain one or more plugins (for example, the [@ckeditor/ckeditor5-image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package contains [several granular plugins](#ckeditor5/latest/features/images/images-overview.html)).

Starting with CKEditor 5 v42.0.0, we collect all plugins in two aggregate packages: `ckeditor5` and `ckeditor5-premium-features`. Using those two is the recommended way of setup. This way you get easy access to all the plugins, without the need to look which plugin is in which package.

<a id="ckeditor5/latest/framework/architecture/plugins.html--common-use-cases">

### Common use cases

Plugins can be pretty much anything. They are pieces of code initialized by the editor if they are configured to be loaded. They can use the richness of the [CKEditor 5 Framework API](../../api/index.html) to enhance the editor or to better integrate it with your application.

Common use cases for plugins are:

* **Editing features**, like bold, heading, linking, or any other feature that the user can use to manipulate the content.
* **Adding semantic value** to the content, like annotations or accessibility features.
* **Third-party services integration**, for injecting external resources into the content, like videos or social network posts.
* **Handling image upload** and image manipulation features.
* **Providing widgets** for easy integration with application structured data.
* **Injecting analysis tools** that help enhance the quality of the content.
* And other infinite possibilities.

<a id="ckeditor5/latest/framework/architecture/plugins.html--creating-plugins">

### Creating plugins

Creating your own plugins is a straightforward task, but it requires good knowledge about some aspects of the CKEditor 5 development environment. The following resources are recommended as a starting point:

* The [Plugin development guide](#ckeditor5/latest/framework/tutorials/crash-course/editor.html).
* The [Using package generator](#ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html), that provides a plugin development environment.

A good understanding of the [CKEditor 5 Framework](#ckeditor5/latest/framework/index.html) is also welcome when it comes to creating plugins.

<a id="ckeditor5/latest/framework/architecture/plugins.html--using-third-party-plugins">

### Using third-party plugins

A great way to enhance your editor with additional features is by using plugins created by the community. Such plugins are available as npm packages, so a quick [search on the “ckeditor5” keyword in npm](https://www.npmjs.com/search?q=ckeditor5) should work as a starting point.

Once you have plugins you want to include, read the [Configuring CKEditor 5 features](#ckeditor5/latest/getting-started/setup/configuration.html) guide.

<a id="ckeditor5/latest/framework/architecture/plugins.html--plugins-and-html-output">

### Plugins and HTML output

Listed below are all official CKEditor 5 packages as well as some partner packages together with their possible HTML output. If a plugin generates a different HTML output depending on its configuration, it is described in the “HTML output” column.

The classes, styles or attributes applied to an HTML element are all **possible** results. It does not mean they all will always be used.

`$block` is a generic structural element that may contain textual content. Features like headings or paragraph implement it to inherit common behaviors. You can read more about it in the [Schema](#ckeditor5/latest/framework/deep-dive/schema.html--generic-items) guide.

If a given plugin does not generate any output, the “HTML output” is described as “None.” Wildcard character `*` means any value is possible.

The data used to generate the following tables comes from the package metadata. You can read more about it in the [package metadata](#ckeditor5/latest/framework/contributing/package-metadata.html) guide.

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-adapter-ckfinder">

#### `ckeditor5-adapter-ckfinder`

Source file: [@ckeditor/ckeditor5-adapter-ckfinder/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-adapter-ckfinder/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                    | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **CKFinder upload adapter**[Feature guide](#ckeditor5/latest/features/images/image-upload/image-upload.html--ckfinder)[API documentation](../../api/module%5Fadapter-ckfinder%5Fuploadadapter-CKFinderUploadAdapter.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-ai">

#### `ckeditor5-ai`

Source file: `@ckeditor/ckeditor5-ai/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                           | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **AI Assistant**[Feature guide](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html)[API documentation](../../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistant.html)                    | None.       |
| **AI Chat**[Feature guide](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)[API documentation](../../api/module%5Fai%5Faichat%5Faichat-AIChat.html)                                                      | None.       |
| **AI Review Mode**[Feature guide](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)[API documentation](../../api/module%5Fai%5Faireviewmode%5Faireviewmode-AIReviewMode.html)                             | None.       |
| **AI Translate**[Feature guide](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)[API documentation](../../api/module%5Fai%5Faitranslate%5Faitranslate-AITranslate.html)                                  | None.       |
| **AI Quick Actions**[Feature guide](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)[API documentation](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActions.html)                     | None.       |
| **AI Editor Integration**[Feature guide](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)[API documentation](../../api/module%5Fai%5Faieditorintegration%5Faieditorintegration-AIEditorIntegration.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-alignment">

#### `ckeditor5-alignment`

Source file: [@ckeditor/ckeditor5-alignment/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-alignment/ckeditor5-metadata.json)

| Plugin                                                                                                                                                   | HTML output                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Alignment**[Feature guide](#ckeditor5/latest/features/text-alignment.html)[API documentation](../../api/module%5Falignment%5Falignment-Alignment.html) | <$block style="text-align:\*">By default, the alignment feature uses the text-align inline style. |
| <$block class="\*">If config.alignment.options is set, these classes are used for alignment instead of inline styles.                                    |                                                                                                   |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-autoformat">

#### `ckeditor5-autoformat`

Source file: [@ckeditor/ckeditor5-autoformat/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-autoformat/ckeditor5-metadata.json)

| Plugin                                                                                                                                                   | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Autoformat**[Feature guide](#ckeditor5/latest/features/autoformat.html)[API documentation](../../api/module%5Fautoformat%5Fautoformat-Autoformat.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-autosave">

#### `ckeditor5-autosave`

Source file: [@ckeditor/ckeditor5-autosave/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-autosave/ckeditor5-metadata.json)

| Plugin                                                                                                                                         | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Autosave**[Feature guide](#ckeditor5/latest/features/autosave.html)[API documentation](../../api/module%5Fautosave%5Fautosave-Autosave.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-basic-styles">

#### `ckeditor5-basic-styles`

Source file: [@ckeditor/ckeditor5-basic-styles/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-basic-styles/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                | HTML output |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Bold**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fbold-Bold.html)                            | <strong>    |
| **Code**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fcode-Code.html)                            | <code>      |
| **Italic**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fitalic-Italic.html)                      | <i>         |
| **Strikethrough**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fstrikethrough-Strikethrough.html) | <s>         |
| **Subscript**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fsubscript-Subscript.html)             | <sub>       |
| **Superscript**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Fsuperscript-Superscript.html)       | <sup>       |
| **Underline**[Feature guide](#ckeditor5/latest/features/basic-styles.html)[API documentation](../../api/module%5Fbasic-styles%5Funderline-Underline.html)             | <u>         |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-block-quote">

#### `ckeditor5-block-quote`

Source file: [@ckeditor/ckeditor5-block-quote/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-block-quote/ckeditor5-metadata.json)

| Plugin                                                                                                                                                      | HTML output  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **Block quote**[Feature guide](#ckeditor5/latest/features/block-quote.html)[API documentation](../../api/module%5Fblock-quote%5Fblockquote-BlockQuote.html) | <blockquote> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-bookmark">

#### `ckeditor5-bookmark`

Source file: [@ckeditor/ckeditor5-bookmark/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-bookmark/ckeditor5-metadata.json)

| Plugin                                                                                                                                          | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Bookmark**[Feature guide](#ckeditor5/latest/features/bookmarks.html)[API documentation](../../api/module%5Fbookmark%5Fbookmark-Bookmark.html) | <a id="\*"> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-case-change">

#### `ckeditor5-case-change`

Source file: `@ckeditor/ckeditor5-case-change/ckeditor5-metadata.json`

| Plugin                                                                                                                                                      | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Case change**[Feature guide](#ckeditor5/latest/features/case-change.html)[API documentation](../../api/module%5Fcase-change%5Fcasechange-CaseChange.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-ckbox">

#### `ckeditor5-ckbox`

Source file: [@ckeditor/ckeditor5-ckbox/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ckbox/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                       | HTML output                                                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CKBox**[Feature guide](#ckeditor5/latest/features/file-management/ckbox.html)[API documentation](../../api/module%5Fckbox%5Fckbox-CKBox.html)                              | <a data-ckbox-resource-id="\*"><figure data-ckbox-resource-id="\*"><img data-ckbox-resource-id="\*">If config.ckbox.ignoreDataId is set to false (off), the asset ID as the data-ckbox-resource-id attribute is added on the inserted elements (by default). |
| **CKBox Image Edit**[Feature guide](#ckeditor5/latest/features/file-management/ckbox.html)[API documentation](../../api/module%5Fckbox%5Fckboximageedit-CKBoxImageEdit.html) | None.                                                                                                                                                                                                                                                        |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-ckfinder">

#### `ckeditor5-ckfinder`

Source file: [@ckeditor/ckeditor5-ckfinder/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ckfinder/ckeditor5-metadata.json)

| Plugin                                                                                                                                                         | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **CKFinder**[Feature guide](#ckeditor5/latest/features/file-management/ckfinder.html)[API documentation](../../api/module%5Fckfinder%5Fckfinder-CKFinder.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-cloud-services">

#### `ckeditor5-cloud-services`

Source file: [@ckeditor/ckeditor5-cloud-services/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-cloud-services/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                   | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Cloud Services**[Feature guide](https://ckeditor.com/ckeditor-cloud-services)[API documentation](../../api/module%5Fcloud-services%5Fcloudservices-CloudServices.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-code-block">

#### `ckeditor5-code-block`

Source file: [@ckeditor/ckeditor5-code-block/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-code-block/ckeditor5-metadata.json)

| Plugin                                                                                                                                                   | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Code blocks**[Feature guide](#ckeditor5/latest/features/code-blocks.html)[API documentation](../../api/module%5Fcode-block%5Fcodeblock-CodeBlock.html) | <pre>       |
| <code class="language-\*">By default, the language of the code block is represented as a CSS class prefixed by language-                                 |             |
| <code class="\*">The CSS class name can be customized via the config.codeBlock.languages array.                                                          |             |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-comments">

#### `ckeditor5-comments`

Source file: `@ckeditor/ckeditor5-comments/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                     | HTML output                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Comments**[Feature guide](#ckeditor5/latest/features/collaboration/comments/comments.html)[API documentation](../../api/module%5Fcomments%5Fcomments-Comments.html)                                      | <comment id="\*" type="\*"\> |
| <comment-end name="\*"><comment-start name="\*">                                                                                                                                                           |                              |
| <\* data-comment-end-after="\*" data-comment-start-before="\*"\>The plugin adds the data-comment-end-after and data-comment-start-before attributes to other elements on which the comment starts or ends. |                              |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-document-outline">

#### `ckeditor5-document-outline`

Source file: `@ckeditor/ckeditor5-document-outline/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                 | HTML output                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Document outline**[Feature guide](#ckeditor5/latest/features/document-outline.html)[API documentation](../../api/module%5Fdocument-outline%5Fdocumentoutline-DocumentOutline.html)   | None.                                                    |
| **Table of contents**[Feature guide](#ckeditor5/latest/features/table-of-contents.html)[API documentation](../../api/module%5Fdocument-outline%5Ftableofcontents-TableOfContents.html) | <div class="table-of-contents table-of-contents\_empty"> |
| <ol><li><a>                                                                                                                                                                            |                                                          |
| <p class="table-of-contents\_\_placeholder">                                                                                                                                           |                                                          |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-easy-image">

#### `ckeditor5-easy-image`

Source file: [@ckeditor/ckeditor5-easy-image/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-easy-image/ckeditor5-metadata.json)

| Plugin                                                                                      | HTML output |
| ------------------------------------------------------------------------------------------- | ----------- |
| **Easy Image**[API documentation](../../api/module%5Feasy-image%5Feasyimage-EasyImage.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-email">

#### `ckeditor5-email`

Source file: `@ckeditor/ckeditor5-email/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                 | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **EmailConfigurationHelper**[Feature guide](#ckeditor5/latest/features/email-editing/email.html)[API documentation](../../api/module%5Femail%5Femailconfigurationhelper-EmailConfigurationHelper.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-emoji">

#### `ckeditor5-emoji`

Source file: [@ckeditor/ckeditor5-emoji/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-emoji/ckeditor5-metadata.json)

| Plugin                                                                                                                                                | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Emoji**[Feature guide](#ckeditor5/latest/features/emoji.html)[API documentation](../../api/module%5Femoji%5Femoji-Emoji.html)                       | None.       |
| **Emoji mention**[Feature guide](#ckeditor5/latest/features/emoji.html)[API documentation](../../api/module%5Femoji%5Femojimention-EmojiMention.html) | None.       |
| **Emoji picker**[Feature guide](#ckeditor5/latest/features/emoji.html)[API documentation](../../api/module%5Femoji%5Femojipicker-EmojiPicker.html)    | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-essentials">

#### `ckeditor5-essentials`

Source file: [@ckeditor/ckeditor5-essentials/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-essentials/ckeditor5-metadata.json)

| Plugin                                                                                        | HTML output |
| --------------------------------------------------------------------------------------------- | ----------- |
| **Essentials**[API documentation](../../api/module%5Fessentials%5Fessentials-Essentials.html) | <br>        |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-export-inline-styles">

#### `ckeditor5-export-inline-styles`

Source file: `@ckeditor/ckeditor5-export-inline-styles/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                           | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Export with Inline Styles**[Feature guide](#ckeditor5/latest/features/export-with-inline-styles.html)[API documentation](../../api/module%5Fexport-inline-styles%5Fexportinlinestyles-ExportInlineStyles.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-export-pdf">

#### `ckeditor5-export-pdf`

Source file: `@ckeditor/ckeditor5-export-pdf/ckeditor5-metadata.json`

| Plugin                                                                                                                                                               | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Export to PDF**[Feature guide](#ckeditor5/latest/features/converters/export-pdf.html)[API documentation](../../api/module%5Fexport-pdf%5Fexportpdf-ExportPdf.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-export-word">

#### `ckeditor5-export-word`

Source file: `@ckeditor/ckeditor5-export-word/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                    | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Export to Word**[Feature guide](#ckeditor5/latest/features/converters/export-word.html)[API documentation](../../api/module%5Fexport-word%5Fexportword-ExportWord.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-find-and-replace">

#### `ckeditor5-find-and-replace`

Source file: [@ckeditor/ckeditor5-find-and-replace/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-find-and-replace/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                             | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Find and replace**[Feature guide](#ckeditor5/latest/features/find-and-replace.html)[API documentation](../../api/module%5Ffind-and-replace%5Ffindandreplace-FindAndReplace.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-font">

#### `ckeditor5-font`

Source file: [@ckeditor/ckeditor5-font/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-font/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                                   | HTML output                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Font background color**[Feature guide](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features)[API documentation](../../api/module%5Ffont%5Ffontbackgroundcolor-FontBackgroundColor.html) | <span style="background-color:\*">                                                                                                                                            |
| **Font color**[Feature guide](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features)[API documentation](../../api/module%5Ffont%5Ffontcolor-FontColor.html)                                | <span style="color:\*">                                                                                                                                                       |
| **Font size**[Feature guide](#ckeditor5/latest/features/font.html--configuring-the-font-size-feature)[API documentation](../../api/module%5Ffont%5Ffontsize-FontSize.html)                                                               | <span class="text-tiny text-small text-big text-huge">If the config.fontSize.options option is not set or it contains predefined named presets, the feature uses class names. |
| <span style="font-size:\*">If the config.fontSize.options option contains numerical values, the font size feature uses the font-size inline style.                                                                                       |                                                                                                                                                                               |
| <\* class="\*" style="\*:\*"\>The plugin can be configured to return any element with any classes and any inline styles.                                                                                                                 |                                                                                                                                                                               |
| **Font family**[Feature guide](#ckeditor5/latest/features/font.html--configuring-the-font-family-feature)[API documentation](../../api/module%5Ffont%5Ffontfamily-FontFamily.html)                                                       | <span style="font-family:\*">By default, the font family feature uses the font-family inline style.                                                                           |
| <\* class="\*" style="\*:\*"\>The plugin can be configured to return any element with any classes and any inline styles.                                                                                                                 |                                                                                                                                                                               |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-footnotes">

#### `ckeditor5-footnotes`

Source file: `@ckeditor/ckeditor5-footnotes/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                  | HTML output                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Footnotes**[Feature guide](#ckeditor5/latest/features/footnotes.html)[API documentation](../../api/module%5Ffootnotes%5Ffootnotes-Footnotes.html)                                                     | <sup class="footnote">                                       |
| <a class="footnote-backlink" href="\*"\>                                                                                                                                                                |                                                              |
| <ol class="footnotes">                                                                                                                                                                                  |                                                              |
| <li class="footnote-definition" id="\*"\>                                                                                                                                                               |                                                              |
| <div class="footnote-content">                                                                                                                                                                          |                                                              |
| **Footnotes Properties**[Feature guide](#ckeditor5/latest/features/footnotes.html--footnote-properties)[API documentation](../../api/module%5Ffootnotes%5Ffootnotesproperties-FootnotesProperties.html) | <ol class="footnotes" style="list-style-type:\*" type="\*"\> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-format-painter">

#### `ckeditor5-format-painter`

Source file: `@ckeditor/ckeditor5-format-painter/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                     | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Format painter**[Feature guide](#ckeditor5/latest/features/format-painter.html)[API documentation](../../api/module%5Fformat-painter%5Fformatpainter-FormatPainter.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-fullscreen">

#### `ckeditor5-fullscreen`

Source file: [@ckeditor/ckeditor5-fullscreen/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-fullscreen/ckeditor5-metadata.json)

| Plugin                                                                                                                                                        | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Fullscreen mode**[Feature guide](#ckeditor5/latest/features/fullscreen.html)[API documentation](../../api/module%5Ffullscreen%5Ffullscreen-Fullscreen.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-heading">

#### `ckeditor5-heading`

Source file: [@ckeditor/ckeditor5-heading/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-heading/ckeditor5-metadata.json)

| Plugin                                                                                                                                     | HTML output                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Title**[Feature guide](#ckeditor5/latest/features/title.html)[API documentation](../../api/module%5Fheading%5Ftitle-Title.html)          | <h1>                                                                                                                                                                                                                                                         |
| **Heading**[Feature guide](#ckeditor5/latest/features/headings.html)[API documentation](../../api/module%5Fheading%5Fheading-Heading.html) | <h2><h3><h4>HTML element may contain classes, styles or attributes, that are created by other plugins, which alter the <$block> element.This element inherits all attributes, classes and styles that are allowed on the <$block> element by other features. |
| <\*>The plugin can be configured to return any element name as a heading.                                                                  |                                                                                                                                                                                                                                                              |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-highlight">

#### `ckeditor5-highlight`

Source file: [@ckeditor/ckeditor5-highlight/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-highlight/ckeditor5-metadata.json)

| Plugin                                                                                                                                              | HTML output                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Highlight**[Feature guide](#ckeditor5/latest/features/highlight.html)[API documentation](../../api/module%5Fhighlight%5Fhighlight-Highlight.html) | <mark class="marker-yellow marker-green marker-pink marker-blue pen-red pen-green">By default, this plugin has 4 markers and 2 pens preconfigured. |
| <mark class="\*">The plugin can be configured to set any classes on the <mark> element.                                                             |                                                                                                                                                    |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-horizontal-line">

#### `ckeditor5-horizontal-line`

Source file: [@ckeditor/ckeditor5-horizontal-line/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-horizontal-line/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                          | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Horizontal line**[Feature guide](#ckeditor5/latest/features/horizontal-line.html)[API documentation](../../api/module%5Fhorizontal-line%5Fhorizontalline-HorizontalLine.html) | <hr>        |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-html-embed">

#### `ckeditor5-html-embed`

Source file: [@ckeditor/ckeditor5-html-embed/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-html-embed/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                | HTML output                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **HTML embed**[Feature guide](#ckeditor5/latest/features/html/html-embed.html)[API documentation](../../api/module%5Fhtml-embed%5Fhtmlembed-HtmlEmbed.html)           | <div class="raw-html-embed"> |
| <\* class="\*" style="\*:\*"\>The plugin can output any arbitrary HTML provided by the user. That HTML is always wrapped with a <div class="raw-html-embed"> element. |                              |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-html-support">

#### `ckeditor5-html-support`

Source file: [@ckeditor/ckeditor5-html-support/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-html-support/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                              | HTML output                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **General HTML Support**[Feature guide](#ckeditor5/latest/features/html/general-html-support.html)[API documentation](../../api/module%5Fhtml-support%5Fgeneralhtmlsupport-GeneralHtmlSupport.html) | <\* class="\*" style="\*:\*" \*="\*"\>The plugin can output any arbitrary HTML configured by config.htmlSupport option. |
| **Data filter**[API documentation](../../api/module%5Fhtml-support%5Fdatafilter-DataFilter.html)                                                                                                    | <\* class="\*" style="\*:\*" \*="\*"\>The plugin can output any arbitrary HTML depending on its configuration.          |
| **Data schema**[API documentation](../../api/module%5Fhtml-support%5Fdataschema-DataSchema.html)                                                                                                    | None.                                                                                                                   |
| **Empty block**[API documentation](../../api/module%5Fhtml-support%5Femptyblock-EmptyBlock.html)                                                                                                    | None.                                                                                                                   |
| **HTML comment**[Feature guide](#ckeditor5/latest/features/html/html-comments.html)[API documentation](../../api/module%5Fhtml-support%5Fhtmlcomment-HtmlComment.html)                              | The plugin can output HTML comments that were added from the editor inital data or by the plugin API.                   |
| **Full page HTML**[Feature guide](#ckeditor5/latest/features/html/full-page-html.html)[API documentation](../../api/module%5Fhtml-support%5Ffullpage-FullPage.html)                                 | None.                                                                                                                   |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-image">

#### `ckeditor5-image`

Source file: [@ckeditor/ckeditor5-image/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                      | HTML output                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto image**[Feature guide](#ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-pasting-a-url-into-the-editor)[API documentation](../../api/module%5Fimage%5Fautoimage-AutoImage.html)          | None.                                                                                                                                                                      |
| **Block image**[Feature guide](#ckeditor5/latest/features/images/images-installation.html--inline-and-block-images)[API documentation](../../api/module%5Fimage%5Fimageblock-ImageBlock.html)                               | <figure class="image">                                                                                                                                                     |
| <img alt="\*" height="\*" sizes="\*" src="\*" srcset="\*" width="\*"\>                                                                                                                                                      |                                                                                                                                                                            |
| **Inline image**[Feature guide](#ckeditor5/latest/features/images/images-installation.html--inline-and-block-images)[API documentation](../../api/module%5Fimage%5Fimageinline-ImageInline.html)                            | <img alt="\*" height="\*" sizes="\*" src="\*" srcset="\*" width="\*"\>                                                                                                     |
| **Image**[Feature guide](#ckeditor5/latest/features/images/images-overview.html)[API documentation](../../api/module%5Fimage%5Fimage-Image.html)                                                                            | None.                                                                                                                                                                      |
| **Image caption**[Feature guide](#ckeditor5/latest/features/images/images-captions.html)[API documentation](../../api/module%5Fimage%5Fimagecaption-ImageCaption.html)                                                      | <figcaption>                                                                                                                                                               |
| **Image resize**[Feature guide](#ckeditor5/latest/features/images/images-resizing.html)[API documentation](../../api/module%5Fimage%5Fimageresize-ImageResize.html)                                                         | <figure class="image\_resized" style="height:\*; width:\*"\>                                                                                                               |
| <img class="image\_resized" style="aspect-ratio:\*; height:\*; width:\*"\>                                                                                                                                                  |                                                                                                                                                                            |
| **Image style**[Feature guide](#ckeditor5/latest/features/images/images-styles.html)[API documentation](../../api/module%5Fimage%5Fimagestyle-ImageStyle.html)                                                              | <figure class="image-style-side image-style-align-left image-style-align-right image-style-block-align-center image-style-block-align-left image-style-block-align-right"> |
| <figure class="\*">The plugin can be configured to set any class names on the <figure> element.                                                                                                                             |                                                                                                                                                                            |
| **Image toolbar**[Feature guide](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar)[API documentation](../../api/module%5Fimage%5Fimagetoolbar-ImageToolbar.html)                            | None.                                                                                                                                                                      |
| **Image upload**[Feature guide](#ckeditor5/latest/features/images/image-upload/image-upload.html)[API documentation](../../api/module%5Fimage%5Fimageupload-ImageUpload.html)                                               | None.                                                                                                                                                                      |
| **Image insert**[Feature guide](#ckeditor5/latest/features/images/images-inserting.html)[API documentation](../../api/module%5Fimage%5Fimageinsert-ImageInsert.html)                                                        | None.                                                                                                                                                                      |
| **Image insert via URL**[Feature guide](#ckeditor5/latest/features/images/images-inserting.html--inserting-images-via-a-source-url)[API documentation](../../api/module%5Fimage%5Fimageinsertviaurl-ImageInsertViaUrl.html) | None.                                                                                                                                                                      |
| **Image utils**[Feature guide](#ckeditor5/latest/features/images/images-overview.html)[API documentation](../../api/module%5Fimage%5Fimageutils-ImageUtils.html)                                                            | None.                                                                                                                                                                      |
| **Image editing**[Feature guide](#ckeditor5/latest/features/images/images-overview.html)[API documentation](../../api/module%5Fimage%5Fimage%5Fimageediting-ImageEditing.html)                                              | None.                                                                                                                                                                      |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-import-word">

#### `ckeditor5-import-word`

Source file: `@ckeditor/ckeditor5-import-word/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                  | HTML output |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Import from Word**[Feature guide](#ckeditor5/latest/features/converters/import-word/import-word.html)[API documentation](../../api/module%5Fimport-word%5Fimportword-ImportWord.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-indent">

#### `ckeditor5-indent`

Source file: [@ckeditor/ckeditor5-indent/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-indent/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                             | HTML output                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Indent**[Feature guide](#ckeditor5/latest/features/indent.html)[API documentation](../../api/module%5Findent%5Findent-Indent.html)                                                                               | None.                                                                                                                                                                                          |
| **Indent block**[Feature guide](#ckeditor5/latest/features/indent.html)[API documentation](../../api/module%5Findent%5Findentblock-IndentBlock.html)                                                               | <$block style="margin-left:\*; margin-right:\*">By default, the plugin uses inline styles for indentation.                                                                                     |
| <$block class="\*">If classes are defined in config.indentBlock.classes, they are used instead of inline styles.                                                                                                   |                                                                                                                                                                                                |
| **Indent block list integration**[Feature guide](#ckeditor5/latest/features/indent.html)[API documentation](../../api/module%5Findent%5Fintegrations%5Findentblocklistintegration-IndentBlockListIntegration.html) | <ol style="margin-left:\*; margin-right:\*"><ul style="margin-left:\*; margin-right:\*"><li style="margin-left:\*; margin-right:\*">By default, the plugin uses inline styles for indentation. |
| <ol class="\*"><ul class="\*"><li class="\*">If classes are defined in config.indentBlock.classes, they are used instead of inline styles.                                                                         |                                                                                                                                                                                                |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-language">

#### `ckeditor5-language`

Source file: [@ckeditor/ckeditor5-language/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-language/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                   | HTML output                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| **Text part language**[Feature guide](#ckeditor5/latest/features/language.html)[API documentation](../../api/module%5Flanguage%5Ftextpartlanguage-TextPartLanguage.html) | <span dir="\*" lang="\*"\> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-line-height">

#### `ckeditor5-line-height`

Source file: `@ckeditor/ckeditor5-line-height/ckeditor5-metadata.json`

| Plugin                                                                                                                                                      | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Line height**[Feature guide](#ckeditor5/latest/features/line-height.html)[API documentation](../../api/module%5Fline-height%5Flineheight-LineHeight.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-link">

#### `ckeditor5-link`

Source file: [@ckeditor/ckeditor5-link/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-link/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                     | HTML output   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| **Autolink**[Feature guide](#ckeditor5/latest/features/link.html--autolink-feature)[API documentation](../../api/module%5Flink%5Fautolink-AutoLink.html)                   | None.         |
| **Link**[Feature guide](#ckeditor5/latest/features/link.html)[API documentation](../../api/module%5Flink%5Flink-Link.html)                                                 | <a href="\*"> |
| <a rel="\*" target="\*"\>If config.link.addTargetToExternalLinks is enabled, then the external links are decorated with rel and target attributes.                         |               |
| <a class="\*" style="\*:\*" \*="\*"\>The plugin can be configured to set any classes, styles or attributes on the <a> tag via custom config.link.decorators configuration. |               |
| **Link image**[Feature guide](#ckeditor5/latest/features/images/images-linking.html)[API documentation](../../api/module%5Flink%5Flinkimage-LinkImage.html)                | <a href="\*"> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-list">

#### `ckeditor5-list`

Source file: [@ckeditor/ckeditor5-list/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-list/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                                                                    | HTML output                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Legacy list**[Feature guide](#ckeditor5/latest/features/lists/lists.html)[API documentation](../../api/module%5Flist%5Flegacylist-LegacyList.html)                                                                                                                      | <ol><ul>                                                                                                                                                                                                     |
| <li>HTML element may contain classes, styles or attributes, that are created by other plugins, which alter the <$block> element.                                                                                                                                          |                                                                                                                                                                                                              |
| **Legacy to-do list**[Feature guide](#ckeditor5/latest/features/lists/todo-lists.html)[API documentation](../../api/module%5Flist%5Flegacytodolist-LegacyTodoList.html)                                                                                                   | <ul class="todo-list">                                                                                                                                                                                       |
| <li>                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                              |
| <label class="todo-list\_\_label">                                                                                                                                                                                                                                        |                                                                                                                                                                                                              |
| <span class="todo-list\_\_label\_\_description">                                                                                                                                                                                                                          |                                                                                                                                                                                                              |
| <input checked="\*" disabled="\*" type="\*"\>                                                                                                                                                                                                                             |                                                                                                                                                                                                              |
| **Legacy list properties**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-styles)[API documentation](../../api/module%5Flist%5Flegacylistproperties-LegacyListProperties.html)                                                               | <ol style="list-style-type:\*" start="\*" reversed="\*"\><ul style="list-style-type:\*" start="\*" reversed="\*"\>                                                                                           |
| **List**[Feature guide](#ckeditor5/latest/features/lists/lists.html)[API documentation](../../api/module%5Flist%5Flist-List.html)                                                                                                                                         | <ol><ul>                                                                                                                                                                                                     |
| <li>                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                              |
| **List formatting**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting-ListFormatting.html)                                                                  | None.                                                                                                                                                                                                        |
| **List item bold integration**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting%5Flistitemboldintegration-ListItemBoldIntegration.html)                    | <li class="ck-list-marker-bold">                                                                                                                                                                             |
| **List item italic integration**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting%5Flistitemitalicintegration-ListItemItalicIntegration.html)              | <li class="ck-list-marker-italic">                                                                                                                                                                           |
| **List item font size integration**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting%5Flistitemfontsizeintegration-ListItemFontSizeIntegration.html)       | <li class="ck-list-marker-font-size ck-list-marker-font-size-tiny ck-list-marker-font-size-small ck-list-marker-font-size-big ck-list-marker-font-size-huge" style="--ck-content-list-marker-font-size:\*"\> |
| **List item font color integration**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting%5Flistitemfontcolorintegration-ListItemFontColorIntegration.html)    | <li class="ck-list-marker-color" style="--ck-content-list-marker-color:\*"\>                                                                                                                                 |
| **List item font family integration**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting)[API documentation](../../api/module%5Flist%5Flistformatting%5Flistitemfontfamilyintegration-ListItemFontFamilyIntegration.html) | <li class="ck-list-marker-font-family" style="--ck-content-list-marker-font-family:\*"\>                                                                                                                     |
| **To-do list**[Feature guide](#ckeditor5/latest/features/lists/todo-lists.html)[API documentation](../../api/module%5Flist%5Ftodolist-TodoList.html)                                                                                                                      | <ul class="todo-list">                                                                                                                                                                                       |
| <li>                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                              |
| <label class="todo-list\_\_label todo-list\_\_label\_without-description">                                                                                                                                                                                                |                                                                                                                                                                                                              |
| <span class="todo-list\_\_label\_\_description">                                                                                                                                                                                                                          |                                                                                                                                                                                                              |
| <input checked="\*" disabled="\*" type="\*"\>                                                                                                                                                                                                                             |                                                                                                                                                                                                              |
| **List properties**[Feature guide](#ckeditor5/latest/features/lists/lists-properties.html)[API documentation](../../api/module%5Flist%5Flistproperties-ListProperties.html)                                                                                               | <ol style="list-style-type:\*" start="\*" reversed="\*" type="\*"\><ul style="list-style-type:\*" start="\*" reversed="\*" type="\*"\>                                                                       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-list-multi-level">

#### `ckeditor5-list-multi-level`

Source file: `@ckeditor/ckeditor5-list-multi-level/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                    | HTML output                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Multi-level list**[Feature guide](#ckeditor5/latest/features/lists/multi-level-lists.html)[API documentation](../../api/module%5Flist-multi-level%5Fmultilevellist-MultiLevelList.html) | <ol class="multi-level-list legal-list" style="list-style-type:\*" start="\*"\><ul class="multi-level-list legal-list" style="list-style-type:\*" start="\*"\> |
| <li>                                                                                                                                                                                      |                                                                                                                                                                |
| <span class="multi-level-list\_\_marker">                                                                                                                                                 |                                                                                                                                                                |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-markdown-gfm">

#### `ckeditor5-markdown-gfm`

Source file: [@ckeditor/ckeditor5-markdown-gfm/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-markdown-gfm/ckeditor5-metadata.json)

| Plugin                                                                                                                                             | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Markdown**[Feature guide](#ckeditor5/latest/features/markdown.html)[API documentation](../../api/module%5Fmarkdown-gfm%5Fmarkdown-Markdown.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-media-embed">

#### `ckeditor5-media-embed`

Source file: [@ckeditor/ckeditor5-media-embed/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-media-embed/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                    | HTML output            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| **Media embed**[Feature guide](#ckeditor5/latest/features/media-embed.html)[API documentation](../../api/module%5Fmedia-embed%5Fmediaembed-MediaEmbed.html)                                               | <figure class="media"> |
| <oembed url="\*">If config.mediaEmbed.previewsInData is turned off, the media preview is not displayed and the media is represented using only the <oembed> tag (by default).                             |                        |
| <div data-oembed-url="\*">If config.mediaEmbed.previewsInData is turned on, the media preview is displayed in the view.                                                                                   |                        |
| <\* url="\*">If config.mediaEmbed.previewsInData is turned off, the plugin can be configured to return any element name specified by config.mediaEmbed.elementName.                                       |                        |
| <div style="height:\*; padding-bottom:\*; position:\*">If config.mediaEmbed.previewsInData is turned on, the media preview is displayed in the view.                                                      |                        |
| <iframe style="height:\*; left:\*; position:\*; top:\*; width:\*" \*allow\*="\*" frameborder="\*" src="\*"\>If config.mediaEmbed.previewsInData is turned on, the media preview is displayed in the view. |                        |
| <\* class="\*" style="\*:\*" \*="\*"\>The plugin can be configured to return any element with any class, inline style, and attribute, via config.mediaEmbed.providers for previewable media.              |                        |
| **Media embed toolbar**[Feature guide](#ckeditor5/latest/features/media-embed.html)[API documentation](../../api/module%5Fmedia-embed%5Fmediaembedtoolbar-MediaEmbedToolbar.html)                         | None.                  |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-mention">

#### `ckeditor5-mention`

Source file: [@ckeditor/ckeditor5-mention/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-mention/ckeditor5-metadata.json)

| Plugin                                                                                                                                     | HTML output                               |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| **Mention**[Feature guide](#ckeditor5/latest/features/mentions.html)[API documentation](../../api/module%5Fmention%5Fmention-Mention.html) | <span class="mention" data-mention="\*"\> |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-merge-fields">

#### `ckeditor5-merge-fields`

Source file: `@ckeditor/ckeditor5-merge-fields/ckeditor5-metadata.json`

| Plugin                                                                                                                                                           | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Merge fields**[Feature guide](#ckeditor5/latest/features/merge-fields.html)[API documentation](../../api/module%5Fmerge-fields%5Fmergefields-MergeFields.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-minimap">

#### `ckeditor5-minimap`

Source file: [@ckeditor/ckeditor5-minimap/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-minimap/ckeditor5-metadata.json)

| Plugin                                                                                                                                            | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Content minimap**[Feature guide](#ckeditor5/latest/features/minimap.html)[API documentation](../../api/module%5Fminimap%5Fminimap-Minimap.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-page-break">

#### `ckeditor5-page-break`

Source file: [@ckeditor/ckeditor5-page-break/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-page-break/ckeditor5-metadata.json)

| Plugin                                                                                                                                                 | HTML output                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| **Page break**[Feature guide](#ckeditor5/latest/features/page-break.html)[API documentation](../../api/module%5Fpage-break%5Fpagebreak-PageBreak.html) | <div class="page-break" style="page-break-after:\*"\> |
| <span style="display:\*">                                                                                                                              |                                                       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-pagination">

#### `ckeditor5-pagination`

Source file: `@ckeditor/ckeditor5-pagination/ckeditor5-metadata.json`

| Plugin                                                                                                                                                              | HTML output                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pagination**[Feature guide](#ckeditor5/latest/features/pagination/pagination.html)[API documentation](../../api/module%5Fpagination%5Fpagination-Pagination.html) | <\* style="page-break-before:\*" data-pagination-page="\*"\>When using editor.getData( { pagination: true } ). Otherwise, no additional elements are generated. |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-paragraph">

#### `ckeditor5-paragraph`

Source file: [@ckeditor/ckeditor5-paragraph/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-paragraph/ckeditor5-metadata.json)

| Plugin                                                                                    | HTML output                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Paragraph**[API documentation](../../api/module%5Fparagraph%5Fparagraph-Paragraph.html) | <p>HTML element may contain classes, styles or attributes, that are created by other plugins, which alter the <$block> element.This element inherits all attributes, classes and styles that are allowed on the <$block> element by other features. |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-paste-from-office">

#### `ckeditor5-paste-from-office`

Source file: [@ckeditor/ckeditor5-paste-from-office/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-paste-from-office/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                          | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Paste from Office**[Feature guide](#ckeditor5/latest/features/pasting/paste-from-office.html)[API documentation](../../api/module%5Fpaste-from-office%5Fpastefromoffice-PasteFromOffice.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-paste-from-office-enhanced">

#### `ckeditor5-paste-from-office-enhanced`

Source file: `@ckeditor/ckeditor5-paste-from-office-enhanced/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                                                     | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Paste from Office Enhanced**[Feature guide](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html)[API documentation](../../api/module%5Fpaste-from-office-enhanced%5Fpastefromofficeenhanced-PasteFromOfficeEnhanced.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-real-time-collaboration">

#### `ckeditor5-real-time-collaboration`

Source file: `@ckeditor/ckeditor5-real-time-collaboration/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                                                                                                                     | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Presence list**[Feature guide](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html--users-presence-list)[API documentation](../../api/module%5Freal-time-collaboration%5Fpresencelist-PresenceList.html)                                              | None.       |
| **Real-time collaborative comments**[Feature guide](#ckeditor5/latest/features/collaboration/comments/comments.html)[API documentation](../../api/module%5Freal-time-collaboration%5Frealtimecollaborativecomments-RealTimeCollaborativeComments.html)                                                     | None.       |
| **Real-time collaborative editing**[Feature guide](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html)[API documentation](../../api/module%5Freal-time-collaboration%5Frealtimecollaborativeediting-RealTimeCollaborativeEditing.html)                          | None.       |
| **Real-time collaborative track changes**[Feature guide](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html)[API documentation](../../api/module%5Freal-time-collaboration%5Frealtimecollaborativetrackchanges-RealTimeCollaborativeTrackChanges.html)                              | None.       |
| **Real-time collaborative revision history**[Feature guide](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html)[API documentation](../../api/module%5Freal-time-collaboration%5Frealtimecollaborativerevisionhistory-RealTimeCollaborativeRevisionHistory.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-remove-format">

#### `ckeditor5-remove-format`

Source file: [@ckeditor/ckeditor5-remove-format/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-remove-format/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                | HTML output |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Remove format**[Feature guide](#ckeditor5/latest/features/remove-format.html)[API documentation](../../api/module%5Fremove-format%5Fremoveformat-RemoveFormat.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-restricted-editing">

#### `ckeditor5-restricted-editing`

Source file: [@ckeditor/ckeditor5-restricted-editing/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-restricted-editing/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                                   | HTML output                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **Restricted editing mode**[Feature guide](#ckeditor5/latest/features/restricted-editing.html)[API documentation](../../api/module%5Frestricted-editing%5Frestrictededitingmode-RestrictedEditingMode.html)                              | <span class="restricted-editing-exception"> |
| <div class="restricted-editing-exception">                                                                                                                                                                                               |                                             |
| **Standard editing mode**[Feature guide](#ckeditor5/latest/features/restricted-editing.html--running-the-standard-editing-mode)[API documentation](../../api/module%5Frestricted-editing%5Fstandardeditingmode-StandardEditingMode.html) | <span class="restricted-editing-exception"> |
| <div class="restricted-editing-exception">                                                                                                                                                                                               |                                             |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-revision-history">

#### `ckeditor5-revision-history`

Source file: `@ckeditor/ckeditor5-revision-history/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                              | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Revision History**[Feature guide](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html)[API documentation](../../api/module%5Frevision-history%5Frevisionhistory-RevisionHistory.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-select-all">

#### `ckeditor5-select-all`

Source file: [@ckeditor/ckeditor5-select-all/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-select-all/ckeditor5-metadata.json)

| Plugin                                                                                                                                                 | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Select all**[Feature guide](#ckeditor5/latest/features/select-all.html)[API documentation](../../api/module%5Fselect-all%5Fselectall-SelectAll.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-show-blocks">

#### `ckeditor5-show-blocks`

Source file: [@ckeditor/ckeditor5-show-blocks/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-show-blocks/ckeditor5-metadata.json)

| Plugin                                                                                                                                                      | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Show blocks**[Feature guide](#ckeditor5/latest/features/show-blocks.html)[API documentation](../../api/module%5Fshow-blocks%5Fshowblocks-ShowBlocks.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-slash-command">

#### `ckeditor5-slash-command`

Source file: `@ckeditor/ckeditor5-slash-command/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                 | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Slash command**[Feature guide](#ckeditor5/latest/features/slash-commands.html)[API documentation](../../api/module%5Fslash-command%5Fslashcommand-SlashCommand.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-source-editing">

#### `ckeditor5-source-editing`

Source file: [@ckeditor/ckeditor5-source-editing/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-source-editing/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                         | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Source code editing**[Feature guide](#ckeditor5/latest/features/source-editing/source-editing.html)[API documentation](../../api/module%5Fsource-editing%5Fsourceediting-SourceEditing.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-source-editing-enhanced">

#### `ckeditor5-source-editing-enhanced`

Source file: `@ckeditor/ckeditor5-source-editing-enhanced/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                                               | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Source editing enhanced**[Feature guide](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html)[API documentation](../../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhanced-SourceEditingEnhanced.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-special-characters">

#### `ckeditor5-special-characters`

Source file: [@ckeditor/ckeditor5-special-characters/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-special-characters/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                              | HTML output |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Special characters**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharacters-SpecialCharacters.html)                                      | None.       |
| **Special characters essentials**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharactersessentials-SpecialCharactersEssentials.html)       | None.       |
| **Special characters arrows**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharactersarrows-SpecialCharactersArrows.html)                   | None.       |
| **Special characters currency**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharacterscurrency-SpecialCharactersCurrency.html)             | None.       |
| **Special characters latin**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharacterslatin-SpecialCharactersLatin.html)                      | None.       |
| **Special characters mathematical**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharactersmathematical-SpecialCharactersMathematical.html) | None.       |
| **Special characters text**[Feature guide](#ckeditor5/latest/features/special-characters.html)[API documentation](../../api/module%5Fspecial-characters%5Fspecialcharacterstext-SpecialCharactersText.html)                         | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-style">

#### `ckeditor5-style`

Source file: [@ckeditor/ckeditor5-style/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-style/ckeditor5-metadata.json)

| Plugin                                                                                                                          | HTML output                                                                             |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Style**[Feature guide](#ckeditor5/latest/features/style.html)[API documentation](../../api/module%5Fstyle%5Fstyle-Style.html) | <\* class="\*">The plugin can output any arbitrary HTML depending on its configuration. |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-table">

#### `ckeditor5-table`

Source file: [@ckeditor/ckeditor5-table/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-table/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                      | HTML output                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table**[Feature guide](#ckeditor5/latest/features/tables/tables.html)[API documentation](../../api/module%5Ftable%5Ftable-Table.html)                                                     | <figure class="table">                                                                                                                                                                                                                                   |
| <table><thead><tbody><tfoot><tr>                                                                                                                                                            |                                                                                                                                                                                                                                                          |
| <td colspan="\*" rowspan="\*"\><th colspan="\*" rowspan="\*"\>                                                                                                                              |                                                                                                                                                                                                                                                          |
| **Table cell properties**[Feature guide](#ckeditor5/latest/features/tables/tables-styling.html)[API documentation](../../api/module%5Ftable%5Ftablecellproperties-TableCellProperties.html) | <td style="background-color:\*; border:\*; border-\*:\*; height:\*; padding:\*; text-align:\*; vertical-align:\*; width:\*"><th style="background-color:\*; border:\*; border-\*:\*; height:\*; padding:\*; text-align:\*; vertical-align:\*; width:\*"> |
| **Table properties**[Feature guide](#ckeditor5/latest/features/tables/tables-styling.html)[API documentation](../../api/module%5Ftable%5Ftableproperties-TableProperties.html)              | <figure class="table-style-align-left table-style-align-center table-style-align-right table-style-block-align-left table-style-block-align-right" style="float:\*; height:\*; width:\*; margin-left:\*; margin-right:\*"\>                              |
| <table style="background-color:\*; border:\*; border-\*:\*">                                                                                                                                |                                                                                                                                                                                                                                                          |
| **Table layout**[Feature guide](#ckeditor5/latest/features/tables/layout-tables.html)[API documentation](../../api/module%5Ftable%5Ftablelayout-TableLayout.html)                           |                                                                                                                                                                                                                                                          |
| **Table toolbar**[Feature guide](#ckeditor5/latest/features/tables/tables-installation.html--toolbars)[API documentation](../../api/module%5Ftable%5Ftabletoolbar-TableToolbar.html)        | None.                                                                                                                                                                                                                                                    |
| **Table caption**[Feature guide](#ckeditor5/latest/features/tables/tables-caption.html)[API documentation](../../api/module%5Ftable%5Ftablecaption-TableCaption.html)                       | <figcaption data-placeholder="\*">                                                                                                                                                                                                                       |
| **Table column resize**[Feature guide](#ckeditor5/latest/features/tables/tables-resize.html)[API documentation](../../api/module%5Ftable%5Ftablecolumnresize-TableColumnResize.html)        | <colgroup>                                                                                                                                                                                                                                               |
| <col style="width:\*">                                                                                                                                                                      |                                                                                                                                                                                                                                                          |
| **PlainTableOutput**[Feature guide](#ckeditor5/latest/features/tables/layout-tables.html)[API documentation](../../api/module%5Ftable%5Fplaintableoutput-PlainTableOutput.html)             | <table><thead><tbody><tr>                                                                                                                                                                                                                                |
| <td colspan="\*" rowspan="\*"\><th colspan="\*" rowspan="\*"\>                                                                                                                              |                                                                                                                                                                                                                                                          |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-template">

#### `ckeditor5-template`

Source file: `@ckeditor/ckeditor5-template/ckeditor5-metadata.json`

| Plugin                                                                                                                                         | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Template**[Feature guide](#ckeditor5/latest/features/template.html)[API documentation](../../api/module%5Ftemplate%5Ftemplate-Template.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-track-changes">

#### `ckeditor5-track-changes`

Source file: `@ckeditor/ckeditor5-track-changes/ckeditor5-metadata.json`

| Plugin                                                                                                                                                                                                                          | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Track changes**[Feature guide](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html)[API documentation](../../api/module%5Ftrack-changes%5Ftrackchanges-TrackChanges.html)                               | None.       |
| **Track changes data**[Feature guide](#ckeditor5/latest/features/collaboration/track-changes/track-changes-data.html)[API documentation](../../api/module%5Ftrack-changes%5Ftrackchangesdata-TrackChangesData.html)             | None.       |
| **Track changes preview**[Feature guide](#ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html)[API documentation](../../api/module%5Ftrack-changes%5Ftrackchangespreview-TrackChangesPreview.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-typing">

#### `ckeditor5-typing`

Source file: [@ckeditor/ckeditor5-typing/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-typing/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                 | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Text transformation**[Feature guide](#ckeditor5/latest/features/text-transformation.html)[API documentation](../../api/module%5Ftyping%5Ftexttransformation-TextTransformation.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-ui">

#### `ckeditor5-ui`

Source file: [@ckeditor/ckeditor5-ui/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-ui/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                   | HTML output |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Block toolbar**[Feature guide](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar)[API documentation](../../api/module%5Fui%5Ftoolbar%5Fblock%5Fblocktoolbar-BlockToolbar.html)       | None.       |
| **Accessibility help**[Feature guide](#ckeditor5/latest/features/accessibility.html)[API documentation](../../api/module%5Fui%5Feditorui%5Faccessibilityhelp%5Faccessibilityhelp-AccessibilityHelp.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-undo">

#### `ckeditor5-undo`

Source file: [@ckeditor/ckeditor5-undo/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-undo/ckeditor5-metadata.json)

| Plugin                                                                                                                          | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Undo**[Feature guide](#ckeditor5/latest/features/undo-redo.html)[API documentation](../../api/module%5Fundo%5Fundo-Undo.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-upload">

#### `ckeditor5-upload`

Source file: [@ckeditor/ckeditor5-upload/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-upload/ckeditor5-metadata.json)

| Plugin                                                                                                                                                                                                                      | HTML output |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Base64 upload adapter**[Feature guide](#ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html)[API documentation](../../api/module%5Fupload%5Fadapters%5Fbase64uploadadapter-Base64UploadAdapter.html) | None.       |
| **Simple upload adapter**[Feature guide](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html)[API documentation](../../api/module%5Fupload%5Fadapters%5Fsimpleuploadadapter-SimpleUploadAdapter.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-uploadcare">

#### `ckeditor5-uploadcare`

Source file: `@ckeditor/ckeditor5-uploadcare/ckeditor5-metadata.json`

| Plugin                                                                                                                     | HTML output                                                                                                         |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Uploadcare**[API documentation](../../api/module%5Fuploadcare%5Fuploadcare-Uploadcare.html)                              | <a data-uploadcare-resource-id="\*"><figure data-uploadcare-resource-id="\*"><img data-uploadcare-resource-id="\*"> |
| **Uploadcare Image Edit**[API documentation](../../api/module%5Fuploadcare%5Fuploadcareimageedit-UploadcareImageEdit.html) | None.                                                                                                               |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-watchdog">

#### `ckeditor5-watchdog`

Source file: [@ckeditor/ckeditor5-watchdog/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-watchdog/ckeditor5-metadata.json)

| Plugin                                                                                                                                                     | HTML output |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| **Watchdog**[Feature guide](#ckeditor5/latest/features/watchdog.html)[API documentation](../../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--ckeditor5-word-count">

#### `ckeditor5-word-count`

Source file: [@ckeditor/ckeditor5-word-count/ckeditor5-metadata.json](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-word-count/ckeditor5-metadata.json)

| Plugin                                                                                                                                                 | HTML output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Word count**[Feature guide](#ckeditor5/latest/features/word-count.html)[API documentation](../../api/module%5Fword-count%5Fwordcount-WordCount.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/plugins.html--mathtype-ckeditor5">

#### `mathtype-ckeditor5`

Source file: _not published yet_

| Plugin                                                                      | HTML output                                                                                                                                                            |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MathType**[Feature guide](#ckeditor5/latest/features/math-equations.html) | <\* \*="\*">For a complete list of available MathML element and attribute names, visit [MDN Web Docs for MathML](https://developer.mozilla.org/en-US/docs/Web/MathML). |

<a id="ckeditor5/latest/framework/architecture/plugins.html--wproofreader-ckeditor5">

#### `wproofreader-ckeditor5`

Source file: _not published yet_

| Plugin                                                                                         | HTML output |
| ---------------------------------------------------------------------------------------------- | ----------- |
| **WProofreader**[Feature guide](#ckeditor5/latest/features/spelling-and-grammar-checking.html) | None.       |

<a id="ckeditor5/latest/framework/architecture/ui-components.html">source file: "ckeditor5/latest/framework/architecture/ui-components.html"</a>

## UI components

The CKEditor 5 framework provides several UI components that can be helpful when developing a new user interface. All UI classes come with the [set()](../../api/module%5Fui%5Fview-View.html#function-set:KEY%5FVALUE) method, which sets the properties of the components, such as labels, icons, placeholders, etc.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--balloon">

### Balloon

A balloon panel is a floating component that can appear depending on the context. It can be pinned to a specific position or added dynamically at the caret position. You can use it to display any UI within the editor. You can create a balloon panel as an instance of the [BalloonPanelView](../../api/module%5Fui%5Fpanel%5Fballoon%5Fballoonpanelview-BalloonPanelView.html) class.

Two positions describe the placement of the ballon. The first one describes the relationship between the element and the pinned balloon. The second one is the position of the balloon arrow. It creates many possible balloon positions:

* `northWestArrowSouthWest`
* `northWestArrowSouthMiddleWest`
* `northWestArrowSouth`
* `northWestArrowSouthMiddleEast`
* `northWestArrowSouthEast`
* `northArrowSouthWest`
* `northArrowSouthMiddleWest`
* `northArrowSouth`
* `northArrowSouthMiddleEast`
* `northArrowSouthEast`
* `northEastArrowSouthWest`
* `northEastArrowSouthMiddleWest`
* `northEastArrowSouth`
* `northEastArrowSouthMiddleEast`
* `northEastArrowSouthEast`
* `southWestArrowNorthWest`
* `southWestArrowNorthMiddleWest`
* `southWestArrowNorth`
* `southWestArrowNorthMiddleEast`
* `southWestArrowNorthEast`
* `southArrowNorthWest`
* `southArrowNorthMiddleWest`
* `southArrowNorth`
* `southArrowNorthMiddleEast`
* `southArrowNorthEast`
* `southEastArrowNorthWest`
* `southEastArrowNorthMiddleWest`
* `southEastArrowNorth`
* `southEastArrowNorthMiddleEast`
* `southEastArrowNorthEast`
* `viewportStickyNorth`

<a id="ckeditor5/latest/framework/architecture/ui-components.html--button">

### Button

There are two basic buttons in the CKEditor 5 UI library: a standard button and a switch. You can instantiate the standard button with the [ButtonView](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) class. By modifying the passed configuration, you can get different button variants and states. The [ButtonLabelView](../../api/module%5Fui%5Fbutton%5Fbuttonlabelview-ButtonLabelView.html) class is a default implementation of the button’s label. It supports dynamic text via the [text](../../api/module%5Fui%5Fbutton%5Fbuttonlabelview-ButtonLabelView.html#member-text) property.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--action">

#### Action

To get an action button, add the `ck-button-action` class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--rounded">

#### Rounded

To get a rounded button, add the `ck-rounded-corners` class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--bold">

#### Bold

To get a bold button, add the `ck-button-bold` class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--icon">

#### Icon

To get a button with an icon, import it first. Then set the `icon` property on the button. You can also add a custom icon to the dropdown by [providing the entire XML string of the icon](#ckeditor5/latest/framework/architecture/ui-library.html--setting-label-icon-and-tooltip). There are also classes you can use to style icons appropriately.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--keystrokes">

#### Keystrokes

To get a button with a shortcut, add the `keystroke` property. To display the shortcut on the button, set the [withKeystroke](../../api/module%5Fui%5Fbutton%5Fbutton-Button.html#member-withKeystroke) property to `true`. If you also add a label, it will display next to the shortcut. You do not need to worry about different shortcuts for different operating systems – the shortcut is relative to the OS. For example, macOS will display the Ctrl+I shortcut as ⌘+I.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--tooltip">

#### Tooltip

To get a button with a tooltip, add the `tooltip` property. You can use it to display additional information on button hover. If you set it to `true`, a label value is displayed.

By default, the tooltip will appear to the south of the button. However, you can adjust its position with the [tooltipPosition](../../api/module%5Fui%5Ftooltipmanager-TooltipPosition.html) property. You can set the property to:

* `n` – North
* `w` – West
* `s` – South
* `e` – East
* `se` – South-east
* `sw` – South-west

A tooltip needs the [TooltipManager](../../api/module%5Fui%5Ftooltipmanager-TooltipManager.html) to work correctly. You need to add it during CKEditor creation.

```
ClassicEditor
    .create( {
        // Editor configuration.
        //
    } )
    .then( editor => {
        this.tooltipManager = new TooltipManager( editor );
    } )
    .catch( error => {
        // Error handling.
        //
    } );

```

<a id="ckeditor5/latest/framework/architecture/ui-components.html--states">

#### States

There are properties you can set to get various button states.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--enabled">

##### Enabled

Buttons are enabled and clickable by default. You can also set the state explicitly by adding the [isEnabled](../../api/module%5Fui%5Fbutton%5Fbutton-Button.html#member-isEnabled) property with a `true` value.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--disabled">

##### Disabled

To disable a button, set the [isEnabled](../../api/module%5Fui%5Fbutton%5Fbutton-Button.html#member-isEnabled) property to `false`.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--on">

##### On

Some actions in the editor can constantly be active. To indicate them, you can set the [isOn](../../api/module%5Fui%5Fbutton%5Fbutton-Button.html#member-isOn) property to `true`.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--switch">

### Switch

You need a different class to instantiate a switch button – [SwitchButtonView](../../api/module%5Fui%5Fbutton%5Fswitchbuttonview-SwitchButtonView.html). To make it work properly, you also need to add an event listener with the [on()](../../api/module%5Fui%5Fbutton%5Fswitchbuttonview-SwitchButtonView.html#function-on) method. Every click triggers the flip of the [isOn](../../api/module%5Fui%5Fbutton%5Fswitchbuttonview-SwitchButtonView.html#member-isOn) property. It is responsible for turning the button on and off.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--dropdown">

### Dropdown

A dropdown consists of two elements: a button and a panel. The button expands the dropdown menu. The dropdown panel can hold any UI element.

You can use the [createDropdown()](../../api/module%5Fui%5Fdropdown%5Futils.html#function-createDropdown) helper method to create a dropdown. By default, it uses the [DropdownButtonView](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fdropdownbuttonview-DropdownButtonView.html) class. You can replace it with the [ButtonView](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) or [SplitButtonView](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fsplitbuttonview-SplitButtonView.html) class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--list">

#### List

Inside a dropdown, you can put a list. To do so, you can use the [addListToDropdown()](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addListToDropdown) helper function. Also, you must add items to a collection before putting them inside the dropdown.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--toolbar">

#### Toolbar

You can use the [addToolbarToDropdown()](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addToolbarToDropdown) helper function to add a toolbar to the dropdown. Inside the toolbar, you can put buttons.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--menu">

#### Menu

Finally, you can add a multi-level menu to a dropdown. Use the [addMenuToDropdown()](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addMenuToDropdown) helper function to simplify the process.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--split-button">

#### Split button

Besides the standard button, you can also use the split button for a dropdown. It has two clickable sections: one for the main action and a second for expanding the dropdown with more options.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--states-2">

#### States

Dropdowns use buttons. Because of that, states and properties remain the same.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--enabled-2">

##### Enabled

Buttons in dropdowns are enabled and clickable by default. You can also set the state explicitly by adding the [isEnabled](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fdropdownbutton-DropdownButton.html#member-isEnabled) property with a `true` value.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--disabled-2">

##### Disabled

To disable a button, set the [isEnabled](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fdropdownbutton-DropdownButton.html#member-isEnabled) property to `false`. It prevents the dropdown from being expanded.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--dialog">

### Dialog

A dialog window is a draggable pop-up that you can display on top of the editor contents. It remains open when the user interacts with the editing area. You can use it to display any detached UI. Dialogs are brought by the [Dialog](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html) plugin.

See the guide about the [API of the dialog system](#ckeditor5/latest/framework/architecture/ui-library.html--dialogs-and-modals).

<a id="ckeditor5/latest/framework/architecture/ui-components.html--modal">

### Modal

Modal is a specific kind of dialog window. While open, it does not allow to interact with the editor content – it has to be closed first. You can use a modal to enforce the user interaction or interrupt them in some important situations.

To create a modal, use the optional [isModal](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-isModal) property of the [Dialog#show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) method.

See the guide about the [API of the dialog system](#ckeditor5/latest/framework/architecture/ui-library.html--dialogs-and-modals).

<a id="ckeditor5/latest/framework/architecture/ui-components.html--icons">

### Icons

The CKEditor 5 library has a collection of icons representing different editor functionalities. Icons are SVG files and follow the style of the surrounding text. You can instantiate an icon with the [IconView](../../api/module%5Fui%5Ficon%5Ficonview-IconView.html) class. The [content](../../api/module%5Fui%5Ficon%5Ficonview-IconView.html#member-content) property stores the SVG source of the icon.

CKEditor 5 features use different icons. You can find them in the `@ckeditor/ckeditor5-icons` package.

You can also [add a custom icon to the dropdown](#ckeditor5/latest/framework/architecture/ui-library.html--setting-label-icon-and-tooltip) by providing the entire XML string of the icon

<a id="ckeditor5/latest/framework/architecture/ui-components.html--input">

### Input

The CKEditor 5 UI library contains some input elements. Usually, they are used in dropdowns and balloon panels, but you can also use them in the main toolbar.

To create them, use the [LabeledFieldView](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html) class, which takes two parameters:

* An instance of the [locale](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html#member-locale) class.
* A helper function, depending on the type of field you want to create.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--text">

#### Text

To create a text field, pass the [createLabeledInputText()](../../api/module%5Fui%5Flabeledfield%5Futils.html#constant-createLabeledInputText) helper function as the second parameter to the [LabeledFieldView](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html) class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--number">

#### Number

To create a number field, pass the [createLabeledInputNumber()](../../api/module%5Fui%5Flabeledfield%5Futils.html#constant-createLabeledInputNumber) helper function as the second parameter to the [LabeledFieldView](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html) class.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--states-3">

#### States

Similarly to buttons, inputs can be enabled or disabled. The property names remain the same.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--enabled-3">

##### Enabled

Inputs are enabled by default. You can also set the state explicitly by adding the [isEnabled](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html#member-isEnabled) property with a `true` value.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--disabled-3">

##### Disabled

To disable an input, set the [isEnabled](../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html#member-isEnabled) property to `false`. It prevents the input from getting users’ data.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--search">

### Search

A search component allows you to filter a list of items based on a specified query. It consists of several components and interfaces:

* To create it, use the main [SearchTextView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html) class.
* The [queryView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html#member-queryView) property allows the user to enter the search query.
* The [infoView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html#member-infoView) property displays additional information about the search results.
* The [filteredView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html#member-filteredView) is a view filtered by the search query. Remember to specify the [filter()](../../api/module%5Fui%5Fsearch%5Ffilteredview-FilteredView.html#function-filter) and [focus()](../../api/module%5Fui%5Fsearch%5Ffilteredview-FilteredView.html#function-focus) methods for this view.

Some sub-components and classes that can help with better presentation of the results:

* The [SearchResultsView](../../api/module%5Fui%5Fsearch%5Fsearchresultsview-SearchResultsView.html) component hosts the filtered and the information views. It is a sub-component of the [SearchTextView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html).
* The [AutocompleteView](../../api/module%5Fui%5Fautocomplete%5Fautocompleteview-AutocompleteView.html) component lists proposed results when the user starts typing and hides them when it is out of focus. It extends the [SearchTextView](../../api/module%5Fui%5Fsearch%5Ftext%5Fsearchtextview-SearchTextView.html) class.
* To group list items, you can use the [ListItemGroupView](../../api/module%5Fui%5Flist%5Flistitemgroupview-ListItemGroupView.html) class.
* To highlight some results (or some text in general), you can use the [HighlightedTextView](../../api/module%5Fui%5Fhighlightedtext%5Fhighlightedtextview-HighlightedTextView.html) class.

Check out the [AI Assistant](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html--demo) feature to see how all the UI pieces work together in a more complex setup.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--spinner">

### Spinner

You can use a spinner to indicate some loading process. There is only one essential property here – [isVisible](../../api/module%5Fui%5Fspinner%5Fspinnerview-SpinnerView.html#member-isVisible). As the name suggests, it controls whether the component is visible. The default is `false`.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--textarea">

### Textarea

The textarea is a component for inserting long blocks of text. You can specify the visible height of the component using the [minRows](../../api/module%5Fui%5Ftextarea%5Ftextareaview-TextareaView.html#member-minRows) property. Specify the [maxRows](../../api/module%5Fui%5Ftextarea%5Ftextareaview-TextareaView.html#member-minRows) property if you do not want the component to exceed a certain height. Textarea dimensions do not need to be fixed, and you can allow users to change them with the [resize](../../api/module%5Fui%5Ftextarea%5Ftextareaview-TextareaView.html#member-resize) option. By default, the property is set to `'none'`, and resizing is not allowed.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--toolbar-2">

### Toolbar

A toolbar is a base for other components. Usually, you would put other UI elements inside it. It can also be nested inside a balloon or dropdown. You can use the [ToolbarView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) class to instantiate a toolbar.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--text-2">

#### Text

You can put different UI elements inside a toolbar. A simple text node is one example. You can use the [items](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html#member-items) property to add a component to a toolbar.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--button-2">

#### Button

You can place any previously listed button inside a toolbar.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--wrap">

#### Wrap

A toolbar automatically wraps if you add more items and the space is limited.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--separator">

#### Separator

You can divide toolbar elements with a separator to create logically connected groups. To instantiate a separator, use the [ToolbarSeparatorView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarseparatorview-ToolbarSeparatorView.html) class. Adding the created instance between desired components will separate them visually.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--multi-row">

#### Multi-row

By default, a toolbar has one row. However, it can span into multiple rows. You can instantiate a line break with the [ToolbarLineBreakView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarlinebreakview-ToolbarLineBreakView.html) class. Adding the created instance after a desired component will place the following UI elements into the next row.

<a id="ckeditor5/latest/framework/architecture/ui-components.html--compact">

#### Compact

There is also a smaller version of a toolbar. To get a compact toolbar, set the [isCompact](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html#member-isCompact) property to `true`.

<a id="ckeditor5/latest/framework/architecture/ui-library.html">source file: "ckeditor5/latest/framework/architecture/ui-library.html"</a>

## UI library

The standard UI library of CKEditor 5 is [@ckeditor/ckeditor5-ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui). It provides base classes and helpers that allow for building a modular UI that seamlessly integrates with other components of the ecosystem.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--views">

### Views

Views use [templates](#ckeditor5/latest/framework/architecture/ui-library.html--templates) to build the UI. They also provide observable interfaces that other features (like [plugins](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--plugins) or [commands](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands)) can use to change the DOM without any actual interaction with the native API.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--definition">

#### Definition

You can define a simple input view class as follows:

```
class SimpleInputView extends View {
    constructor( locale ) {
        super( locale );

        // An entry point to binding observables with DOM attributes,
        // events, and text nodes.
        const bind = this.bindTemplate;

        // Views define their interface (state) using observable properties.
        this.set( {
            isEnabled: false,
            placeholder: ''
        } );

        this.setTemplate( {
            tag: 'input',
            attributes: {
                class: [
                    'foo',
                    // The value of "view#isEnabled" will control the presence
                    // of the class.
                    bind.if( 'isEnabled', 'ck-enabled' ),
                ],

                // The HTML "placeholder" attribute is also controlled by the observable.
                placeholder: bind.to( 'placeholder' ),
                type: 'text'
            },
            on: {
                // DOM "keydown" events will fire the "view#input" event.
                keydown: bind.to( 'input' )
            }
        } );
    }

    setValue( newValue ) {
        this.element.value = newValue;
    }
}

```

Views encapsulate the DOM they render. Because the UI is organized according to the _view-per-tree_ rule, it is clear which view is responsible for which part of the UI. It is unlikely that a collision occurs between two features writing to the same DOM node.

More often than not, views become children of other views (collections), nodes in the [UI view tree](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree):

```
class ParentView extends View {
    constructor( locale ) {
        super( locale );

        const childA = new SimpleInputView( locale );
        const childB = new SimpleInputView( locale );

        this.setTemplate( {
            tag: 'div',
            children: [
                childA,
                childB
            ]
        } );
    }
}

const parent = new ParentView( locale );

parent.render();

// This will insert <div><input .. /><input .. /></div>.
document.body.appendChild( parent.element );

```

It is also possible to create standalone views that do not belong to any collection. They must be [rendered](../../api/module%5Fui%5Fview-View.html#function-render) before injection into the DOM:

```
const view = new SimpleInputView( locale );

view.render();

// This will insert <input class="foo" type="text" placeholder="" />
document.body.appendChild( view.element );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--interaction">

#### Interaction

Features can interact with the state of the DOM via the observable properties of the view, so the following:

```
view.isEnabled = true;
view.placeholder = 'Type some text';

```

will result in:

```
<input class="foo ck-enabled" type="text" placeholder="Type some text" />

```

Alternatively, they can [bind](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--event-system-and-observables) them directly to their own observable properties:

```
view.bind( 'placeholder', 'isEnabled' ).to( observable, 'placeholderText', 'isEnabled' );

// The following will be automatically reflected in the "view#placeholder" and
// "view.element#placeholder" HTML attribute in the DOM.
observable.placeholderText = 'Some placeholder';

```

Also, since views propagate DOM events, features can now react to the user actions:

```
// Each "keydown" event in the input will execute a command.
view.on( 'input', () => {
    editor.execute( 'myCommand' );
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--best-practices">

#### Best practices

A complete view should provide an interface for the features, encapsulating DOM nodes and attributes. Features should not touch the DOM of the view using the native API. Any kind of interaction must be handled by the view that owns a [element](../../api/module%5Fui%5Fview-View.html#member-element) to avoid collisions:

```
// This will change the value of the input.
view.setValue( 'A new value of the input.' );

// WRONG! This is **NOT** the right way to interact with the DOM because it
// collides with an observable binding to the "#placeholderText". The value will
// be permanently overridden when the state of the observable changes.
view.element.placeholder = 'A new placeholder';

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--templates">

### Templates

[Templates](../../api/module%5Fui%5Ftemplate-Template.html) render DOM elements and text nodes in the UI library. Used primarily by [views](#ckeditor5/latest/framework/architecture/ui-library.html--views), they are the lowest layer of the UI connecting the application to the web page.

Templates support [observable properties](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--event-system-and-observables) bindings and handle native DOM events. A simple template can look like this:

```
new Template( {
    tag: 'p',
    attributes: {
        class: [
            'foo',
            bind.to( 'class' )
        ],
        style: {
            backgroundColor: 'yellow'
        }
    },
    on: {
        click: bind.to( 'clicked' )
    },
    children: [
        'A paragraph.'
    ]
} ).render();

```

It renders to an HTML element:

```
<p class="foo bar" style="background-color: yellow;">A paragraph.</p>

```

where `observable#class` is `"bar"`. The `observable` in the example above can be a [view](#ckeditor5/latest/framework/architecture/ui-library.html--views) or any object which is [observable](../../api/module%5Futils%5Fobservablemixin-Observable.html). When the value of the `class` attribute changes, the template updates the `class` attribute in the DOM. From now on the element is permanently bound to the state of the application.

Similarly, when rendered, the template also takes care of DOM events. A binding to the `click` event in the definition makes the `observable` always fire the `clicked` event upon an action in the DOM. This way the `observable` provides an event interface of the DOM element and all the communication should pass through it.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree">

### View collections and the UI tree

Views are organized into [collections](../../api/module%5Fui%5Fviewcollection-ViewCollection.html), which manage their elements and propagate DOM events even further. Adding or removing a view in a collection moves the [view’s element](../../api/module%5Fui%5Fview-View.html#member-element) in the DOM to reflect the position.

Each editor UI has a “root view” (like [ClassicEditor#view](../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html#member-view)), which can be found under `editor.ui.view`. Such a view usually defines the container element of the editor and the undermost view collections that other features can populate.

For instance, the `BoxedEditorUiView` class defines two collections:

* [top](../../api/module%5Fui%5Feditorui%5Fboxed%5Fboxededitoruiview-BoxedEditorUIView.html#member-top) – A collection that hosts the toolbar.
* [main](../../api/module%5Fui%5Feditorui%5Fboxed%5Fboxededitoruiview-BoxedEditorUIView.html#member-main) – A collection that contains the editable area of the editor.

It also inherits the [body](../../api/module%5Fui%5Feditorui%5Feditoruiview-EditorUIView.html#member-body) collection which resides directly in the `<body>` of the web page. It stores floating elements like [balloon panels](../../api/module%5Fui%5Fpanel%5Fballoon%5Fballoonpanelview-BalloonPanelView.html).

Plugins can populate the root view collections with their children. Such child views become a part of the UI tree and will be managed by the editor. This means that, for example, they will be initialized and destroyed along with the editor.

```
class MyPlugin extends Plugin {
    init() {
        const editor = this.editor;
        const view = new MyPluginView();

        editor.ui.top.add( view );
    }
}

```

`MyPluginView` can [create its view collections](../../api/module%5Fui%5Fview-View.html#function-createCollection) and populate them during the life cycle of the editor. There is no limit to the depth of the UI tree, which usually looks like this:

```
EditorUIView
    ├── "top" collection
    │    └── ToolbarView
    │        └── "items" collection
    │            ├── DropdownView
    │            │    ├── ButtonView
    │            │    └── PanelView
    │            ├── ButtonViewA
    │            ├── ButtonViewB
    │            └── ...
    ├── "main" collection
    │    └── InlineEditableUIView
    └── "body" collection
        ├── BalloonPanelView
        │    └── "content" collection
        │        └── ToolbarView
        ├── BalloonPanelView
        │    └── "content" collection
        │        └── ...
        └── ...

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--using-the-existing-components">

### Using the existing components

The framework provides some common [components](../../api/ui.html) like [ButtonView](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) or [ToolbarView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html). They can be helpful when developing a new user interface.

For example, to create a toolbar with some buttons inside, you need to import the `ToolbarView` and `ButtonView` classes first:

Create the toolbar and a couple of buttons with labels first. Then append the buttons to the toolbar:

```
const toolbar = new ToolbarView();
const buttonFoo = new ButtonView();
const buttonBar = new ButtonView();

buttonFoo.set( {
    label: 'Foo',
    withText: true
} );

buttonBar.set( {
    label: 'Bar',
    withText: true
} );

toolbar.items.add( buttonFoo );
toolbar.items.add( buttonBar );

```

The toolbar can now join the [UI tree](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree) or it can be injected straight into the DOM. To keep the example simple, proceed with the latter scenario:

```
toolbar.render();

document.body.appendChild( toolbar.element );

```

The result should look like this:

The toolbar renders but it does not do much. To execute an action when the button is clicked, you must define a listener. To shorten the code and instead of two listeners define just one, the buttons can [delegate](../../api/module%5Futils%5Femittermixin-Emitter.html#function-delegate) the [execute](../../api/module%5Fui%5Fbutton%5Fbutton-Button.html#event-execute) event to their parent:

```
buttonFoo.delegate( 'execute' ).to( toolbar );
buttonBar.delegate( 'execute' ).to( toolbar );

toolbar.on( 'execute', evt => {
    console.log( `The "${ evt.source.label }" button was clicked!` );
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--dropdowns">

#### Dropdowns

The framework implements the [dropdown](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html) component which can host any sort of UI in its panel. It is composed of a [button](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-buttonView) (to open the dropdown) and a [panel](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-panelView) (the container).

The button can be either:

* A standard [ButtonView](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html).
* A [SplitButtonView](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fsplitbuttonview-SplitButtonView.html), for more complex use cases.

The dropdown panel exposes its [children](../../api/module%5Fui%5Fdropdown%5Fdropdownpanelview-DropdownPanelView.html#member-children) collection which aggregates the child [views](../../api/module%5Fui%5Fview-View.html). The most common views displayed in the dropdown panel are:

* [ListView](../../api/module%5Fui%5Flist%5Flistview-ListView.html) \- dropdown list
* [ToolbarView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) \- dropdown toolbar
* [DropdownMenuRootListView](../../api/module%5Fui%5Fdropdown%5Fmenu%5Fdropdownmenurootlistview-DropdownMenuRootListView.html) \- dropdown menu

The framework provides a set of helpers to make the dropdown creation process easier. It is still possible to compose a custom dropdown from scratch using the base classes. However, for most needs, we highly recommend using provided helper functions.

The [createDropdown](../../api/module%5Fui%5Fdropdown%5Futils.html#function-createDropdown) helper creates a [DropdownView](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html) with either a [ButtonView](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) or a [SplitButtonView](../../api/module%5Fui%5Fdropdown%5Fbutton%5Fsplitbuttonview-SplitButtonView.html).

This kind of (default) dropdown comes with a set of behaviors:

* It closes the panel when it loses the focus, for example, when the user moved the focus elsewhere.
* It closes the panel upon the [execute](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#event-execute) event.
* It focuses the view hosted in the panel, for example, when navigating the toolbar using the keyboard.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--setting-label-icon-and-tooltip">

##### Setting label, icon, and tooltip

To customize the button of the dropdown, use the [buttonView](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-buttonView) property. It gives direct access to the [ButtonView instance](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) used by your dropdown.

To control the label of the dropdown, first make it visible using the [withText](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html#member-withText) property. Then set the text of the [label](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html#member-label):

```
const dropdownView = createDropdown( locale );

dropdownView.buttonView.set( {
    withText: true,
    label: 'Label of the button',
} );

```

The dropdown button can display an icon too. First, import the SVG file. Then pass it to the [icon](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html#member-icon) property of the button:

```
import iconFile from 'path/to/icon.svg';

// The code that creates a dropdown view.
// ...

dropdownView.buttonView.set( {
    icon: iconFile
} );

```

You can use one of the [icons available in the editor](#ckeditor5/latest/framework/architecture/ui-components.html--icons). You can also add a custom icon to the dropdown by providing the entire XML string of the icon, like in this example:

```
<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><path d="M10.187 17H5.773c-.637 0-1.092-.138-1.364-.415-.273-.277-.409-.718-.409-1.323V4.738c0-.617.14-1.062.419-1.332.279-.27.73-.406 1.354-.406h4.68c.69 0 1.288.041 1.793.124.506.083.96.242 1.36.478.341.197.644.447.906.75a3.262 3.262 0 0 1 .808 2.162c0 1.401-.722 2.426-2.167 3.075C15.05 10.175 16 11.315 16 13.01a3.756 3.756 0 0 1-2.296 3.504 6.1 6.1 0 0 1-1.517.377c-.571.073-1.238.11-2 .11zm-.217-6.217H7v4.087h3.069c1.977 0 2.965-.69 2.965-2.072 0-.707-.256-1.22-.768-1.537-.512-.319-1.277-.478-2.296-.478zM7 5.13v3.619h2.606c.729 0 1.292-.067 1.69-.2a1.6 1.6 0 0 0 .91-.765c.165-.267.247-.566.247-.897 0-.707-.26-1.176-.778-1.409-.519-.232-1.31-.348-2.375-.348H7z"/></svg>

```

If you want to have an icon that changes its color depending on the state of the button, you should remove all of the fill and stroke attributes.

The `withText` and `icon` properties are independent so your dropdown can have:

* Just a text label.
* Just an icon.
* Both a label and an icon at the same time.

Dropdowns can also display tooltips when hovered. Use the [tooltip](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html#member-tooltip) property of the button to enable this feature. You can include keystroke information in the tooltip or create custom tooltips. Check out the documentation of the property to learn more.

```
dropdownView.buttonView.set( {
    // The tooltip text will repeat the label.
    tooltip: true
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--adding-a-list-to-a-dropdown">

##### Adding a list to a dropdown

The [ListView](../../api/module%5Fui%5Flist%5Flistview-ListView.html) can be added to a dropdown using the [addListToDropdown](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addListToDropdown) helper.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--adding-a-toolbar-to-a-dropdown">

##### Adding a toolbar to a dropdown

A [ToolbarView](../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) can be added to a dropdown using the [addToolbarToDropdown](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addToolbarToDropdown) helper.

A common practice is making the main dropdown button [enabled](../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-isEnabled) when one of the toolbar items is enabled:

```
// Enable the dropdown's button when any of the toolbar items is enabled.
dropdownView.bind( 'isEnabled' ).toMany( buttons, 'isEnabled',
    ( ...areEnabled ) => areEnabled.some( isEnabled => isEnabled )
);

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--adding-a-menu-to-a-dropdown">

##### Adding a menu to a dropdown

A multi-level menu can be added to a dropdown using the [addMenuToDropdown](../../api/module%5Fui%5Fdropdown%5Futils.html#function-addMenuToDropdown) helper.

Most probably you will want to perform some action when one of the defined buttons is pressed:

```
dropdownView.on( 'execute', evt => {
    const id = evt.source.id;

    console.log( id ); // E.g. will print "menu_1_a" when "Item A" is pressed.
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--dialogs-and-modals">

#### Dialogs and modals

The framework provides the UI dialog component. The dialog system in CKEditor 5 is brought by the [Dialog plugin](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html). It offers API for displaying [views](#ckeditor5/latest/framework/architecture/ui-library.html--views) in dialogs. In a sense, this plugin corresponds to another one that manages views in balloons (popovers) across the UI ([ContextualBalloon plugin](../../api/module%5Fui%5Fpanel%5Fballoon%5Fcontextualballoon-ContextualBalloon.html)).

Dialog is a pop-up window that does not close when the user clicks outside of it. It allows for interacting with the editor and its content while being open (unless it is a modal, which blocks the interaction with the rest of the page until closed). A dialog is also [draggable](../../api/module%5Fui%5Fbindings%5Fdraggableviewmixin.html#function-DraggableViewMixin) with a mouse or touch if you configure it to display a [header](#ckeditor5/latest/framework/architecture/ui-library.html--header). Only one dialog can be open at a time – opening another one closes the previously visible one.

Check out these [example plugins](#ckeditor5/latest/framework/architecture/plugins.html) that display:

* a [dialog window](#ckeditor5/latest/framework/architecture/ui-components.html--dialog),
* a [modal window](#ckeditor5/latest/framework/architecture/ui-components.html--modal).

Learn more about the [structure and behavior](#ckeditor5/latest/framework/architecture/ui-library.html--structure-and-behavior) of dialog windows.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--modals">

##### Modals

Modals are similar to the dialogs – they share the same structure rules, API, etc. The major difference is that while a modal is open, the user cannot interact with the editor or the rest of the page. They are covered with a non-transparent overlay. You can use a modal, for example, to force the user to take one of the specified actions.

To create a modal, use the optional [isModal](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-isModal) property of the [Dialog#show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) method:

```
editor.plugins.get( 'Dialog' ).show( {
    isModal: true,

    // The rest of the dialog definition.
} );

```

There are different ways to close a modal:

* Clicking the “Close” button in the corner (if the [header](#ckeditor5/latest/framework/architecture/ui-library.html--header) is visible).
* Using the Esc keystroke or one of the [action buttons](#ckeditor5/latest/framework/architecture/ui-library.html--action-buttons).

<a id="ckeditor5/latest/framework/architecture/ui-library.html--structure-and-behavior">

##### Structure and behavior

A dialog can consist of three parts, each of which is optional:

* The [header](#ckeditor5/latest/framework/architecture/ui-library.html--header) (also used as a drag handler).
* The [content](#ckeditor5/latest/framework/architecture/ui-library.html--content) (the body of the dialog).
* The [action buttons](#ckeditor5/latest/framework/architecture/ui-library.html--action-buttons) area (a collection of buttons).

You cannot change the order of these parts.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--header">

###### Header

A header may consist of any combination of three elements:

* The icon.
* The title.
* The “Close” button.

By default, the “Close” button (“X”) is added to the header as long as you provide an icon or a title. To hide it, set the `hasCloseButton` flag to `false`:

<a id="ckeditor5/latest/framework/architecture/ui-library.html--content">

###### Content

This part can be a single [view](#ckeditor5/latest/framework/architecture/ui-library.html--views) or a collection of views. They will be displayed directly inside the body of the dialog. Below, you can find an example of how to insert a block of text into the dialog.

```
const textView = new View( locale );

textView.setTemplate( {
    tag: 'div',
    attributes: {
        style: {
            padding: 'var(--ck-spacing-large)',
            whiteSpace: 'initial',
            width: '100%',
            maxWidth: '500px'
        },
        tabindex: -1
    },
    children: [
        'This is a sample content of the dialog.',
        'You can put here text, images, inputs, buttons, etc.'
    ]
} );

editor.plugins.get( 'Dialog' ).show( {
    title: 'Info dialog with text',
    content: textView,

    // The rest of the dialog definition.
} );

```

The content of the dialog determines its dimensions. If you want to display a dialog with a fixed size, make sure the content has a fixed size too. For displaying long text, we recommend setting `max-height: [fixed value]` together with `overflow: auto` on the content container (element). This will restrict the vertical space the dialog will use on the screen.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--action-buttons">

###### Action buttons

The last segment of the dialog is the actions area, where the buttons are displayed. You can fully customize their behavior using the `onCreate()` and `onExecute()` callbacks. Below you can find an example of the configuration for the four custom buttons:

* The “OK” button that closes the dialog and has a custom CSS class set.
* The “Set custom title” button that changes the dialog title.
* The “This button will be enabled in…” button that changes its state after a few seconds.
* The “Cancel” button that closes the dialog.

```
editor.plugins.get( 'Dialog' ).show( {
    // ...

    actionButtons: [
        {
            label: 'OK',
            class: 'ck-button-action',
            withText: true,
            onExecute: () => dialog.hide()
        },
        {
            label: 'Set custom title',
            withText: true,
            onExecute: () => {
                dialog.view.headerView.label = 'New title';
            }
        },
        {
            label: 'This button will be enabled in 5...',
            withText: true,
            onCreate: buttonView => {
                buttonView.isEnabled = false;
                let counter = 5;

                const interval = setInterval( () => {
                    buttonView.label = `This button will be enabled in ${ --counter }...`;

                    if ( counter === 0 ) {
                        clearInterval( interval );
                        buttonView.label = 'This button is now enabled!';
                        buttonView.isEnabled = true;
                    }
                }, 1000 );
            }
        },
        {
            label: 'Cancel',
            withText: true,
            onExecute: () => dialog.hide()
        }
    ]
} );

```

You can also bind the button state to the content to ensure some required actions were taken by the user. See the example of the “Yes/No modal” definition. It requires the user to mark the checkbox to close the modal:

```
// First, create the content to be injected into a the modal.
// In this example a simple switch button is used.
const switchButtonView = new SwitchButtonView( locale );

switchButtonView.set( {
    label: t( 'I accept the terms and conditions' ),
    withText: true
} );

// Manage the state of the switch button when the user clicks it.
switchButtonView.on( 'execute', () => {
    switchButtonView.isOn = !switchButtonView.isOn;
} );

// Then show the modal.
editor.plugins.get( 'Dialog' ).show( {
    id: 'yesNoModal',
    isModal: true,
    title: 'Accept the terms to enable the "Yes" button',
    hasCloseButton: false,
    content: switchButtonView,
    actionButtons: [
        {
            label: t( 'Yes' ),
            class: 'ck-button-action',
            withText: true,
            onExecute: () => dialog.hide(),
            onCreate: buttonView => {
                // By default, the "Yes" button in the dialog is disabled.
                buttonView.isEnabled = false;

                // The "Yes" button will be enabled as soon as the user
                // toggles the switch button.
                switchButtonView.on( 'change:isOn', () => {
                    buttonView.isEnabled = switchButtonView.isOn;
                } );
            }
        },
        {
            label: t( 'No' ),
            withText: true,
            onExecute: () => dialog.hide()
        }
    ],
    // Disable the "Esc" key.
    onShow: dialog => {
        dialog.view.on( 'close', ( evt, data ) => {
            if ( data.source === 'escKeyPress' ) {
                evt.stop();
            }
        }, { priority: 'high' } );
    }
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--accessibility">

##### Accessibility

Dialogs provide full keyboard accessibility.

* While a dialog is open, strike the Ctrl+F6 combination to move the focus between the editor and the dialog.
* You can also close a dialog at any time by pressing the Esc key (even if the “Close” button is hidden).
* To navigate through the dialog, use the Tab and Shift+Tab keystrokes.

The content of the dialog is also available for screen readers.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--api">

##### API

The dialog’s lifecycle (creating and destroying) is managed by the [Dialog plugin](../../api/module%5Fui%5Fdialog%5Fdialog.html). It provides two public methods: [show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) and [hide()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-hide). Both of them fire the respective events ([show](../../api/module%5Fui%5Fdialog%5Fdialog-DialogShowEvent.html) and [hide](../../api/module%5Fui%5Fdialog%5Fdialog-DialogHideEvent.html)), so it is possible to hook after or before them.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--the-dialogshow-method">

###### The `Dialog#show()` method

The [Dialog#show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) method hides any visible dialog and displays a new one. It accepts a dialog definition that allows to shape the structure and behavior of the dialog. See the [DialogDefinition](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html) API to learn more about the possibilities it gives.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--the-dialogshowid-event">

###### The `Dialog#show:[id]` event

When the [Dialog#show()](#ckeditor5/latest/framework/architecture/ui-library.html--the-dialogshow-method) function gets called, a namespaced [show:\[id\]](../../api/module%5Fui%5Fdialog%5Fdialog-DialogShowEvent.html) event is fired. This allows for customizing the dialog’s behavior.

For example, you can change the default position of the “Find and replace” dialog from the editor corner to the bottom with the following code:

You can also listen to the general `'show'` event to customize all dialogs at once.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--the-dialoghide-method">

###### The `Dialog#hide()` method

Executing the [Dialog#hide()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-hide) method will hide the dialog. It will also call the [onHide()](#ckeditor5/latest/framework/architecture/ui-library.html--using-the-onshow-and-onhide-callbacks) callback if it was provided in the respective [Dialog#show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) method call.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--the-dialoghideid-event">

###### The `Dialog#hide:[id]` event

Similarly to the [show:\[id\]](#ckeditor5/latest/framework/architecture/ui-library.html--the-dialogshowid-event) event, the [hide:\[id\]](../../api/module%5Fui%5Fdialog%5Fdialog-DialogHideEvent.html) event gets fired when the [Dialog#hide()](#ckeditor5/latest/framework/architecture/ui-library.html--the-dialoghide-method) is called. It allows for executing custom actions:

```
// Logs after the "Find and Replace" dialog gets hidden.
editor.plugins.get( 'Dialog' ).on( 'hide:findAndReplace', () => {
    console.log( 'The "Find and Replace" dialog was hidden.' );
} );

```

You can also listen to the general `'hide'` event to react to all dialogs at once.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--the-dialogviewclose-event">

###### The `DialogView#close` event

When the Esc key or the “Close” button is pressed with the dialog open, the [DialogView](../../api/module%5Fui%5Fdialog%5Fdialogview-DialogView.html) fires the [close](../../api/module%5Fui%5Fdialog%5Fdialogview-DialogViewCloseEvent.html) event with the according `source` parameter. Then the [Dialog plugin](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html) hides (and destroys) the dialog.

You can control this behavior, for example, disabling the Esc key handling:

```
editor.plugins.get( 'Dialog' ).view.on( 'close', ( evt, data ) => {
    if ( data.source === 'escKeyPress' ) {
        evt.stop();
    }
} )

```

You can also pass such code directly in the `show()` method call in the `onShow` callback:

```
editor.plugins.get( 'Dialog' ).show( {
    onShow: dialog => {
        dialog.view.on( 'close', ( evt, data ) => {
            if ( data.source === 'escKeyPress' ) {
                evt.stop();
            }
        }, { priority: 'high' } );
    }
    // The rest of the dialog definition.
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--using-the-onshow-and-onhide-callbacks">

###### Using the `onShow` and `onHide` callbacks

The [DialogDefinition](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html) accepts two callbacks. They allow customizing the actions after the dialog is shown ([onShow()](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-onShow)) and hidden ([onHide()](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-onHide)).

The `onShow` callback allows you to manipulate the dialog values or set additional listeners. In the [DialogView#event:close event](#ckeditor5/latest/framework/architecture/ui-library.html--the-dialogviewclose-event) section you can find an example of how to disable the Esc key with it. The code below shows how to bootstrap the dynamic field filling.

The `onHide` callback will be particularly helpful to reset the state of the component or its controller once the dialog is closed.

```
// Executing inside a class with the "controller" property that has the state connected to the dialog.
editor.plugins.get( 'Dialog' ).show( {
    onHide: dialog => {
        this.controller.reset(); // Reset the controller state once the dialog is hidden.
    },
    // The rest of the dialog definition.
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--visibility-and-positioning">

##### Visibility and positioning

Only one dialog can be visible at the same time. Opening another dialog (from the same or another editor instance) will close the previous dialog.

If not specified otherwise, the dialog will display in the center of the editor’s editing area. A modal will display in the center of the screen. Custom dialogs can have their position set to one of the pre-configured options (see [DialogViewPosition](../../api/module%5Fui%5Fdialog%5Fdialogview.html#constant-DialogViewPosition)). The relative positioning is disabled once the dialog is manually dragged by the user.

* When you develop your dialog, specify the [position](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-position) property in a definition passed to the [Dialog#show()](../../api/module%5Fui%5Fdialog%5Fdialog-Dialog.html#function-show) method, for instance:
* To change the position of an existing dialog or manage positions dynamically, use the [show](../../api/module%5Fui%5Fdialog%5Fdialog-DialogShowEvent.html) event listener (see the [example code](#ckeditor5/latest/framework/architecture/ui-library.html--the-dialogshowid-event)).

Sometimes, when the content of the dialog or the environment changes (for example, the editor is resized), you may want to force-update the position of the dialog. This will restore its position to the [configured default](../../api/module%5Fui%5Fdialog%5Fdialog-DialogDefinition.html#member-position). It will also reset any manual positioning (dragging) done by the user. To do so, use the [updatePosition](../../api/module%5Fui%5Fdialog%5Fdialogview-DialogView.html#function-updatePosition) method.

```
editor.plugins.get( 'Dialog' ).view.updatePosition();

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--best-practices-2">

#### Best practices

For the best user experience, the editing view should get [focused](../../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-focus) upon any user action (like executing a command) to make sure the editor retains focus:

```
// Execute some action on the "dropdown#execute" event.
dropdownView.buttonView.on( 'execute', () => {
    editor.execute( 'command', { value: "command-value" } );
    editor.editing.view.focus();
} );

```

<a id="ckeditor5/latest/framework/architecture/ui-library.html--keystrokes-and-focus-management">

### Keystrokes and focus management

The framework offers built-in classes that help manage keystrokes and focus in the UI. They are useful when it comes to bringing accessibility features to the application.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--focus-tracker">

#### Focus tracker

The [FocusTracker](../../api/module%5Futils%5Ffocustracker-FocusTracker.html) class can observe some HTML elements and determine if one of them is focused either by the user (clicking, typing) or using the `HTMLElement.focus()` DOM method.

To register elements in the tracker, use the [add()](../../api/module%5Futils%5Ffocustracker-FocusTracker.html#function-add) method:

```
focusTracker.add( document.querySelector( '.some-element' ) );
focusTracker.add( viewInstance.element );

```

Observing the focus tracker’s [isFocused](../../api/module%5Futils%5Ffocustracker-FocusTracker.html#member-isFocused) observable property allows you to determine whether one of the registered elements is currently focused:

```
focusTracker.on( 'change:isFocused', ( evt, name, isFocused ) => {
    if ( isFocused ) {
        console.log( 'The', focusTracker.focusedElement, 'is focused now.' );
    } else {
        console.log( 'The elements are blurred.' );
    }
} );

```

This information is useful when implementing a certain type of UI whose behavior depends on the focus. For example, contextual panels and floating balloons containing forms should hide when the user decides to abandon them.

Learn more about the focus tracker class in the [Deep dive into focus tracking](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class) guide.

<a id="ckeditor5/latest/framework/architecture/ui-library.html--keystroke-handler">

#### Keystroke handler

The [KeystrokeHandler](../../api/module%5Futils%5Fkeystrokehandler-KeystrokeHandler.html) listens to the keystroke events fired by an HTML element or any of its descendants. It executes pre-defined actions when the keystroke is pressed. Usually, each [view](#ckeditor5/latest/framework/architecture/ui-library.html--views) creates its keystroke handler instance. It takes care of the keystrokes fired by the elements the view has rendered.

To define the scope of the keystroke handler in the DOM, use the [listenTo()](../../api/module%5Futils%5Fkeystrokehandler-KeystrokeHandler.html#function-listenTo) method:

```
keystrokeHandler.listenTo( document.querySelector( '.some-element' ) );
keystrokeHandler.listenTo( viewInstance.element );

```

Keystroke action callbacks are functions. To prevent the default action of the keystroke and stop further propagation, use the `cancel()` function provided in the callback.

```
keystrokeHandler.set( 'Tab', ( keyEvtData, cancel ) => {
    console.log( 'Tab was pressed!' );

    // This keystroke has been handled and can be canceled.
    cancel();
} );

```

When you assign multiple callbacks to the same keystroke, you can use priorities to decide which one to handle first and whether to execute other callbacks at all:

```
keystrokeHandler.set( 'Ctrl+A', ( keyEvtData ) => {
    console.log( 'A normal priority listener.' );
} );

keystrokeHandler.set( 'Ctrl+A', ( keyEvtData ) => {
    console.log( 'A high priority listener.' );

    // The normal priority listener will not be executed.
    cancel();
}, { priority: 'high' } );

```

Pressing Ctrl+A will log:

```
"A high priority listener."

```

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html">source file: "ckeditor5/latest/framework/contributing/changelog-entries.html"</a>

## Changelog entries

CKEditor 5 uses Markdown file-based changelog system inspired by tools like Changesets. Contributions are noted in a human-readable Markdown files stored in the repository. These files describe the nature of the change (bug fix, feature, breaking change, etc.) and are committed alongside the actual code. These entries will be automatically compiled into the final changelog during the release process.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--how-to-create-a-new-file">

### How to create a new file

Create a new Markdown file in the `.changelog/` directory to add a changelog entry. Each file **must** describe **one change only**. You can create as many files as you need to explain the changes.

This command creates a new Markdown file with a file name based on the current date and Git branch name: `YYYYMMDDHHMMSS_{branch-name}.md`. The branch name is automatically slugified (only letters, numbers, `-`, and `_` are allowed).

_Example: `20250617103000fix-toolbar-alignment.md`_

The file will include a predefined frontmatter template. **You must manually fill in the details** (like `type`, `scope`, `closes`, and the summary of your change).

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--format-of-a-changelog-entry">

### Format of a changelog entry

Each changelog entry is a Markdown file with a frontmatter section followed by a summary and optional context. Here is a breakdown of all available fields:

| Field            | Required? | Description                                                                                                                |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| type             | ✅ Yes     | Type of the change. See the allowed values and their impact in the table below.                                            |
| scope            | ❌ No      | Affected package(s), using short names like ckeditor5-core.                                                                |
| closes           | ❌ No      | List of issues this change resolves. Use numbers (123), full references (ckeditor/ckeditor5#123), or full URLs.            |
| see              | ❌ No      | Related issues that provide context but are not directly resolved by this change. Same format as closes.                   |
| communityCredits | ❌ No      | GitHub usernames of external contributors who should be credited for this change.                                          |
| _(body)_         | ✅ Yes     | After the frontmatter, add a short and meaningful summary of the change. Optionally include extended context or rationale. |

The changelog entry format is designed to be both human-friendly and machine-readable. It uses a simple frontmatter structure followed by a short description of the change. Each field in the frontmatter serves a specific purpose, from determining the entry’s visibility to linking it with related issues or acknowledging community contributions.

Using these fields correctly ensures that the changelog remains accurate, meaningful, and consistent across releases. The sections below explain the available fields in more detail and provide guidance on when and how to use them.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--allowed-values-for-the-type-field">

#### Allowed values for the `type` field

| Type                  | Release | Description                                                                                                                                              |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Feature               | minor   | A new feature. Introduces user-facing functionality.                                                                                                     |
| Fix                   | patch   | A bug fix. Use also for small improvements that do not qualify as new features.                                                                          |
| Other                 | patch   | Enhancement or refactor. It is not a fix or feature. Example: public API cleanup.                                                                        |
| Major breaking change | major   | A change in the integration layer or the plugin development API. See [versioning policy](#ckeditor5/latest/updating/versioning-policy.html) for details. |
| Minor breaking change | minor   | Low-level customizable API layer. See [versioning policy](#ckeditor5/latest/updating/versioning-policy.html) for details.                                |

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--package-name-scope">

#### Package name (`scope`)

Changes affect one or more packages. List the package that was most impacted by the change first.

However, it is possible to skip this part if many packages are affected. This usually indicates a generic change. In this case, having all the packages listed would reduce the readability of the changelog.

The package name is based on the npm package name, but the `@ckeditor/` prefix is stripped.

If your change is related to the main package, use `ckeditor5` as the package name.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--referencing-issues">

#### Referencing issues

When creating PRs that address specific issues, use the following messages to indicate them.

* `Closes` – When the PR resolves an issue.
* `See` – When the PR references an issue but has not resolved it yet.

Both fields (`closes` and `see`) can contain multiple references, but they must follow the same format:

* `14724` – A simple issue number.
* `ckeditor/ckeditor5#14724` – A full reference to an issue in the CKEditor 5 repository.
* `https://github.com/ckeditor/ckeditor5/issues/14724` – A full URL to an issue in the CKEditor 5 repository.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--giving-credit">

#### Giving credit

When closing a PR submitted by a non-core contributor, add information about the contributor to the changelog entry file using the `communityCredits` field. It should contain a list of GitHub usernames of contributors who should be credited for this change.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--description">

#### Description

Write a concise and meaningful summary of the change. This main message will appear in the public changelog, so keep it clear, user-facing, and relevant.

Use the `ClassName#methodName()` format when referencing methods. This ensures consistency across all entries.

**Example:**

```
MarkerCollection#has()

```

You may include multiple sentences if additional context is helpful.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--examples-of-correct-entry-formatting">

#### Examples of correct entry formatting

A new feature without any breaking changes.

```
---
type: Feature
scope:
  - ckeditor5-ui
closes:
  - 1
---

Added support for RTL languages.

RTL content will now be rendered correctly.

```

A generic bug fix for an existing feature that affects many packages (closes two tickets):

```
---
type: Fix
closes:
  - 2
  - 3
---

The editor will be great again.

```

An improvement that is not backward compatible and sent by a non-core contributor. Public API was changed:

```
---
type: Other
scope:
  - ckeditor5-utils
closes:
  - 9
---

Extracted the `utils#foo()` to a separate package.

```

```
---
type: Feature
scope:
  - ckeditor5-engine
closes:
  - 9
---

Introduced the `engine#foo()` method.

```

```
---
type: Major breaking change
scope:
  - ckeditor5-utils
see:
  - 9
---

The `utils#foo()` method was moved to the `engine` package.

```

For the entries shown above, the changelog will look like this:

```
Changelog
=========

## [51.0.0](https://github.com/ckeditor/ckeditor5/compare/v50.1.1...v51.0.0) (June 17, 2025)

### MAJOR BREAKING CHANGES [ℹ️](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/versioning-policy.html#major-and-minor-breaking-changes)

* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: The `utils#foo()` method was moved to the `engine` package. See [#9](https://github.com/ckeditor/ckeditor5/issues/9).

### Features

* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Introduced the `engine#foo()` method. Closes [#9](https://github.com/ckeditor/ckeditor5/issues/9).
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: Added support for RTL languages. Closes [#1](https://github.com/ckeditor/ckeditor5/issues/1).

  RTL content will now be rendered correctly.

### Bug fixes

* The editor will be great again. Closes [#2](https://github.com/ckeditor/ckeditor5/issues/2), [#3](https://github.com/ckeditor/ckeditor5/issues/3).

### Other changes

* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: Extracted the `utils#foo()` to a separate package. Closes [#9](https://github.com/ckeditor/ckeditor5/issues/9).

```

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--fixing-errors">

#### Fixing errors

If the entry message is wrong, you can fix it by editing the Markdown file in the `.changelog/` directory and preparing a new pull request.

<a id="ckeditor5/latest/framework/contributing/changelog-entries.html--handling-pull-requests">

### Handling pull requests

When creating a pull request, you may propose a changelog entry (as recommended in the pull request template).

The reviewer must validate the proposed message and apply necessary changes. It can be done using the GitHub interface (as suggestions).

As a reviewer, make sure to check the following aspects of the proposed changelog entry and add or correct them if needed:

* The language and grammar of the message
* The type of the change
* Mentioned issue(s) number
* Breaking changes
* Any additional relevant information

You must be aware that the message will end up in the changelog and must be understandable in the broad context of the entire editor. It is not for you – it is for other developers.

When closing a PR, you do not have to copy anything. Pick your merge strategy (for example, “Squash and merge”), and GitHub will handle the rest.

<a id="ckeditor5/latest/framework/contributing/code-style.html">source file: "ckeditor5/latest/framework/contributing/code-style.html"</a>

## Code style

[CKEditor 5 development environment](#ckeditor5/latest/framework/contributing/development-environment.html) has ESLint enabled both as a pre-commit hook and on CI. This means that code style issues are detected automatically. Additionally, `.editorconfig` files are present in every repository to automatically adjust your IDE settings (if it is configured to read them).

Here is a quick summary of these rules.

<a id="ckeditor5/latest/framework/contributing/code-style.html--general">

### General

**LF for line endings**. Never use CRLF.

The recommended maximum **line length is 120 characters**. It cannot exceed 140 characters.

<a id="ckeditor5/latest/framework/contributing/code-style.html--whitespace">

### Whitespace

**No trailing spaces**. Empty lines should not contain any spaces.

Whitespace **inside parenthesis** and **before and after operators**:

```
function foo( a, b, c, d, e ) {
    if ( a > b ) {
        c = ( d + e ) * 2;
    }
}

foo( bar() );

```

No whitespace for an **empty parenthesis**:

```
const a = () => {
    // Statements.
    // ...
};

a();

```

No whitespace **before colon and semicolon**:

```
let a, b;

a( 1, 2, 3 );

for ( const i = 0; i < 100; i++ ) {
    // Statements.
    // ...
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--indentation">

### Indentation

Indentation with **tab**, for both code and comments. Never use spaces.

If you want to have the code readable, set the **tab** to **4 spaces** in your IDE.

```
class Bar {
    a() {
        while ( b in a ) {
            if ( b == c ) {
                // Statements.
                // ...
            }
        }
    }
}

```

**Multiple lines condition**. Use **one tab** for each line:

```
if (
    some != really.complex &&
    condition || with &&
    ( multiple == lines )
) {
    // Statements.
    // ...
}

while (
    some != really.complex &&
    condition || with &&
    ( multiple == lines )
) {
    // Statements.
    // ...
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--braces">

### Braces

Braces **start at the same line** as the head statement and end aligned with it:

```
function a() {
    // Statements.
    // ...
}

if ( a ) {
    // Statements.
    // ...
} else if ( b ) {
    // Statements.
    // ...
} else {
    // Statements.
    // ...
}

try {
    // Statements.
    // ...
} catch ( e ) {
    // Statements.
    // ...
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--blank-lines">

### Blank lines

The code should read like a book, so put blank lines between “paragraphs” of code. This is an open and contextual rule, but some recommendations would be to separate the following sections:

* variable, class and function declarations,
* `if()`, `for()` and similar blocks,
* steps of an algorithm,
* `return` statements,
* comment sections (comments should be preceded with a blank line, but if they are the “paragraph” themselves, they should also be followed with one),
* etc.

Example:

```
class Foo extends Plugin {
    constructor( editor ) {
        super( editor );

        /**
        * Some documentation...
        */
        this.foo = new Foo();

        /**
        * Some documentation...
        */
        this.isBar = false;
    }

    method( bar ) {
        const editor = this.editor;
        const selection = editor.model.document.selection;

        for ( const range of selection.getRanges() ) {
            const position = range.start;

            if ( !position ) {
                return false;
            }

            // At this stage this and this need to happen.
            // We considered doing this differently, but it has its shortcomings.
            // Refer to the tests and issue #3456 to learn more.

            const result = editor.model.checkSomething( position );

            if ( result ) {
                return true;
            }
        }

        return true;
    }

    performAlgorithm() {
        // 1. Do things A and B.
        this.a();
        this.b();

        // 2. Check C.
        if ( c() ) {
            d();
        }

        // 3. Check whether we are fine.
        const areWeFine = 1 || 2 || 3;

        this.check( areWeFine );

        // 4. Finalize.
        this.finalize( areWeFine );

        return areWeFine;
    }
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--multi-line-statements-and-calls">

### Multi-line statements and calls

Whenever there is a multi-line function call:

* Put the first parameter in a new line.
* Put every parameter in a separate line indented by one tab.
* Put the last closing parenthesis in a new line, at the same indentation level as the beginning of the call.

Examples:

```
const myObj = new MyClass(
    'Some long parameters',
    'To make this',
    'Multi line'
);

fooBar(
    () => {
        // Statements.
        // ...
    }
);

fooBar(
    new MyClass(
        'Some long parameters',
        'To make this',
        'Multi line'
    )
);

fooBar(
    'A very long string',
    () => {
        // Some kind of a callback.
        // ...
    },
    5,
    new MyClass(
        'It looks well',
        paramA,
        paramB,
        new ShortClass( 2, 3, 5 ),
        'Even when nested'
    )
);

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--strings">

### Strings

Use **single quotes**:

```
const a = 'I\'m an example for quotes';

```

Long strings can be **concatenated with plus** (`+`):

```
const html =
    'Line 1\n' +
    'Line 2\n' +
    'Line 3';

```

or you can use template strings. The second and third line will be indented in this case:

```
const html =
    `Line 1
    Line 2
    Line 3`;

```

Strings of HTML should use indentation for readability:

```
const html =
    `<p>
        <span>${ a }</span>
    </p>`;

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--comments">

### Comments

* Comments are always **preceded by a blank line**.
* Comments start with a **capital first letter** and require a period at the end (since they are sentences).
* There must be a **single space at the start** of the text, right after the comment token.

**Block comments** (`/** ... */`) are used for **documentation only**. Asterisks are aligned with space:

```
/**
 * Documentation for the following method.
 *
 * @returns {Object} Something.
 */
someMethod() {
    // Statements.
    // ...
}

```

All **other comments** use **line comments** (`//`):

```
// A comment about the following statement.
foo();

// Multiple line comments
// go through several
// line comments as well.

```

**Comments related to tickets or issues** should not describe the whole issue fully. A short description should be used instead, together with the ticket number in parenthesis:

```
// Do this otherwise because of a Safari bug. (#123)
foo();

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--linting">

### Linting

CKEditor 5 development environment uses [ESLint](https://eslint.org) and [stylelint](https://stylelint.io/).

A couple of useful links:

* [Disabling ESLint with inline comments](https://eslint.org/docs/latest/use/configure/).
* [CKEditor 5 ESLint preset](https://github.com/ckeditor/ckeditor5-linters-config/blob/master/packages/eslint-config-ckeditor5/eslint.config.mjs) (npm: [eslint-config-ckeditor5](http://npmjs.com/package/eslint-config-ckeditor5)).
* [CKEditor 5 stylelint preset](https://github.com/ckeditor/ckeditor5-linters-config/blob/master/packages/stylelint-config-ckeditor5/.stylelintrc) (npm: [stylelint-config-ckeditor5](https://www.npmjs.com/package/stylelint-config-ckeditor5)).

<a id="ckeditor5/latest/framework/contributing/code-style.html--visibility-levels">

### Visibility levels

Each class property (including methods, symbols, getters, or setters) can be public, protected, or private. The default visibility is public, so you should not document that a property is public – there is no need to do this.

Additional rules apply to private properties:

* The names of private and protected properties that are exposed in a class prototype (or in any other way) should be prefixed with an underscore.
* When documenting a private variable that is not added to a class prototype (or exposed in any other way), `//` comments should be used and using `@private` is not necessary.
* A symbol property (like `this[ Symbol( 'symbolName' ) ]`) should be documented as `@property {Type} _symbolName`.

Example:

```
class Foo {
    /**
    * The constructor (public, as its visibility isn't defined).
    */
    constructor() {
        /**
        * Public property.
        */
        this.foo = 1;

        /**
        * Protected property.
        *
        * @protected
        */
        this._bar = 1;

        /**
        * @private
        * @property {Number} _bom
        */
        this[ Symbol( 'bom' ) ] = 1;
    }

    /**
    * @private
    */
    _somePrivateMethod() {}
}

// Some private helper.
//
// @returns {Number}
function doSomething() {
    return 1;
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--accessibility">

#### Accessibility

The table below shows the accessibility of properties:

|            | Class | Package | Subclass | World |
| ---------- | ----- | ------- | -------- | ----- |
| @public    | yes   | yes     | yes      | yes   |
| @protected | yes   | yes     | yes      | no    |
| @private   | yes   | no      | no       | no    |

(yes – accessible, no – not accessible)

For instance, a protected property is accessible from its own class in which it was defined, from its whole package, and from its subclasses (even if they are not in the same package).

<a id="ckeditor5/latest/framework/contributing/code-style.html--getters">

### Getters

You can use ES6 getters to simplify class API:

```
class Position {
    // More methods.
    // ...

    get offset() {
        return this.path[ this.path.length - 1 ];
    }
}

```

A getter should feel like a natural property. There are several recommendations to follow when creating getters:

* They should be fast.
* They should not throw.
* They should not change the object state.
* They should not return new instances of an object every time (so `foo.bar == foo.bar` is true). It is OK to create a new instance for the first call and cache it if it is possible.

<a id="ckeditor5/latest/framework/contributing/code-style.html--order-within-class-definition">

### Order within class definition

Within the class definition, order the methods and properties as follows:

1. Constructor.
2. Getters and setters.
3. Iterators.
4. Public instance methods.
5. Public static methods.
6. Protected instance methods.
7. Protected static methods.
8. Private instance methods.
9. Private static methods.

The order within each group is left for the implementer.

<a id="ckeditor5/latest/framework/contributing/code-style.html--tests">

### Tests

There are some special rules and tips for tests.

<a id="ckeditor5/latest/framework/contributing/code-style.html--test-organization">

#### Test organization

* Always use an outer `describe()` in a test file. Do not allow any globals, especially hooks (`beforeEach()`, `after()`, etc.) outside the outermost `describe()`.
* The outermost `describe()` calls should create meaningful groups, so when all tests are run together a failing TC can be identified within the code base. For example:  
```  
describe( 'Editor', () => {  
    describe( 'constructor()', () => {  
        it( /* ... */ );  
    } );  
    // More test cases.  
    // ...  
} );  
```  
Using titles like `utils` is not fine as there are multiple utilities in the entire project. `Table utils` would be better.
* Test descriptions (`it()`) should be written like documentation (what you do and what should happen), for example, _“the foo dialog closes when the X button is clicked”_. Also, _“…case 1”_, _“…case 2”_ in test descriptions are not helpful.
* Avoid test descriptions like _“does not crash when two ranges get merged.”_ Instead, explain what is actually expected to happen. For instance: _“leaves 1 range when two ranges get merged.”_
* Most often, using words like “correctly,” “works fine” is a code smell. Think about the requirements – when writing them you do not say that feature X should “work fine.” You document how it should work.
* Ideally, it should be possible to recreate an algorithm just by reading the test descriptions.
* Avoid covering multiple cases under one `it()`. It is OK to have multiple assertions in one test, but not to test, for example, how method `foo()` works when it is called with 1, then with 2, then 3, etc. There should be a separate test for each case.
* Every test should clean up after itself, including destroying all editors and removing all elements that have been added.

<a id="ckeditor5/latest/framework/contributing/code-style.html--test-implementation">

#### Test implementation

* Avoid using real timeouts. Use [fake timers](https://sinonjs.org/releases/latest/fake-timers/) instead **when possible**. Timeouts make tests really slow.
* However, do not over-optimize (especially since performance is not a priority in tests). In most cases, it is completely fine (and hence recommended) to create a separate editor for every `it()`.
* We aim at having 100% coverage of _all distinctive scenarios_. Covering 100% branches in the code is not the goal here – it is a by-product of covering real scenarios.  
Think about this: when you fix a bug by adding a parameter to an existing function call, you do not affect code coverage (that line was called anyway). However, you had a bug, meaning that your test suite did not cover it. Therefore, a test must be created for that code change.
* It should be `expect( x ).to.equal( y )`. **NOT**: ~~`expect( x ).to.be.equal( y )`~~.
* When using Sinon spies, pay attention to the readability of assertions and failure messages.

  * Use named spies, for example:  
  ```  
  const someCallbackSpy = sinon.spy().named( 'someCallback' );  
  const myMethodSpy = sinon.spy( obj, 'myMethod' );  
  ```
  * Use [sinon-chai assertions](https://www.chaijs.com/plugins/sinon-chai/)  
  ```  
  expect( myMethodSpy ).to.be.calledOnce  
  // expected myMethod to be called once but was called twice  
  ```

<a id="ckeditor5/latest/framework/contributing/code-style.html--naming">

### Naming

<a id="ckeditor5/latest/framework/contributing/code-style.html--javascript-code-names">

#### JavaScript code names

Variables, functions, namespaces, parameters and all undocumented cases must be named in [lowerCamelCase](http://en.wikipedia.org/wiki/CamelCase):

```
let a;
let myLongNamedVariable = true;

function foo() {}

function longNamedFunction( example, longNamedParameter ) {}

```

Classes must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase):

```
class MyClass() {}

const a = new MyClass();

```

Mixins must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase), post-fixed with “Mixin”:

```
const SomeMixin = {
    method1: /* ... */,
    method2: /* ... */
};

```

Global namespacing variables must be named in [ALLCAPS](http://en.wikipedia.org/wiki/All%5Fcaps):

```
const CKEDITOR_TRANSLATIONS = {};

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--private-properties-and-methods">

##### Private properties and methods

Private properties and methods are **prefixed with an underscore**:

```
CKEDITOR._counter;
something._doInternalTask();

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--methods-and-functions">

##### Methods and functions

Methods and functions are **almost always** verbs or actions:

```
// Good
execute();
this.getNextNumber()

// Bad
this.editable();
this.status();

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--properties-and-variables">

##### Properties and variables

Properties and variables are **almost always** nouns:

```
const editor = this.editor;
this.name;
this.editable;

```

**Boolean properties and variables** are **always** prefixed by an auxiliary verb:

```
this.isDirty;
this.hasChildren;
this.canObserve;
this.mustRefresh;

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--buttons-commands-and-plugins">

#### Buttons, Commands and Plugins

<a id="ckeditor5/latest/framework/contributing/code-style.html--buttons">

##### Buttons

All buttons should follow the **verb + noun** or the **noun** convention. Examples:

* The **verb + noun** convention:  
  * `insertTable`
  * `selectAll`
  * `uploadImage`
* The **noun** convention:  
  * `bold`
  * `mediaEmbed`
  * `restrictedEditing`

<a id="ckeditor5/latest/framework/contributing/code-style.html--commands">

##### Commands

As for commands, it is trickier. There are more combinations of their names possible than there are for buttons. Examples:

* The **feature-related** convention:  
  * **noun-based** case:  
    * `codeBlock`
    * `fontColor`
    * `shiftEnter`
  * **verb-based** case:  
    * `indent`
    * `removeFormat`
    * `selectAll`
* The **feature + sub-feature** convention:  
  * `imageStyle`
  * `imageTextAlternative`
  * `tableAlignment`

For commands, the **noun + verb** (or the **feature + action**) naming conventions **should not be used**, because it does not sound natural (_what do_ vs. _do what_). In most cases the proper name should start with the **action** followed by the **feature** name:

* `checkTodoList`
* `insertTable`
* `uploadImage`

<a id="ckeditor5/latest/framework/contributing/code-style.html--plugins">

##### Plugins

Plugins should follow the **feature** or the **feature + sub-feature** convention. Examples:

* The **feature** convention:  
  * `Bold`
  * `Paragraph`
  * `SpecialCharacters`
* The **feature + sub-feature** convention:  
  * `ImageResize`
  * `ListProperties`
  * `TableClipboard`

Plugins must be named in [UpperCamelCase](http://en.wikipedia.org/wiki/CamelCase).

<a id="ckeditor5/latest/framework/contributing/code-style.html--shortcuts">

#### Shortcuts

For local variables **commonly accepted short versions** for long names are fine:

```
const attr, doc, el, fn, deps, err, id, args, uid, evt, env;

```

The following are **the only short versions accepted for property names**:

```
this.lang;
this.config;
this.id;
this.env;

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--acronyms-and-proper-names">

#### Acronyms and proper names

Acronyms and, partially, proper names are naturally written in uppercase. This may stand against code style rules described above – especially when there is a need to include an acronym or a proper name in a variable or class name. In such case, one should follow these rules:

* Acronyms:  
  * All lowercase if at the beginning of the variable name: `let domError`.
  * Default camel case at the beginning of the class name: `class DomError`.
  * Default camel case inside the variable or class name: `function getDomError()`.
* Proper names:  
  * All lowercase if at the beginning of the variable: `let ckeditorError`.
  * Original case if at the beginning of the class name: `class CKEditorError`.
  * Original case inside the variable or class name: `function getCKEditorError()`.

However, two-letter acronyms and proper names (if originally written uppercase) should be uppercase. For example: `getUI`, not `getUi`.

<a id="ckeditor5/latest/framework/contributing/code-style.html--css-classes">

#### CSS classes

CSS class naming pattern is based on [BEM](https://en.bem.info/) methodology and code style. All names are in lowercase with an optional dash (`-`) between the words.

Top–level building **blocks** begin with a mandatory `ck-` prefix:

```
.ck-dialog
.ck-toolbar
.ck-dropdown-menu

```

**Elements** belonging to the block namespace are delimited by double underscore (`__`):

```
.ck-dialog__header
.ck-toolbar__group
.ck-dropdown-menu__button-collapser

```

**Modifiers** are delimited by a single underscore (`_`). Key-value modifiers  
follow the `block-or-element_key_value` naming pattern:

```
/* Block modifier */
.ck-dialog_hidden
/* Element modifier */
.ck-toolbar__group_collapsed
/* Block modifier as key_value  */
.ck-dropdown-menu_theme_some-theme

```

In HTML:

```
<div class="ck-reset_all ck-dialog ck-dialog_theme_lark ck-dialog_visible">
    <div class="ck-dialog__top ck-dialog__top_small">
        <h1 class="ck-dialog__top-title">Title of the dialog</h1>
        ...
    </div>
    ...
</div>

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--id-attributes">

#### ID attributes

HTML ID attribute naming pattern follows [CSS classes](#ckeditor5/latest/framework/contributing/code-style.html--css-classes) naming guidelines. Each ID must begin with the `ck-` prefix and consist of dash–separated (`-`) words in lowercase:

```
<div id="ck">...</div>
<div id="ck-unique-div">...</div>
<div id="ck-a-very-long-unique-identifier">...</div>

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--file-names">

#### File names

File and directory names must follow a standard that makes their syntax easy to predict:

* All lowercase.
* Only alphanumeric characters are accepted.
* Words are separated by dashes (`-`) ([kebab-case](https://en.wikipedia.org/wiki/Letter%5Fcase#Special%5Fcase%5Fstyles)).  
  * Code entities are considered single words, so the `DataProcessor` class is defined in the `dataprocessor.js` file.
  * However, a test file covering for “mutations in multi-root editors”: `mutations-in-multi-root-editors.js`.
* HTML files have the `.html` extension.

<a id="ckeditor5/latest/framework/contributing/code-style.html--examples">

##### Examples

* `ckeditor.js`
* `tools.js`
* `editor.js`
* `dataprocessor.js`
* `build-all.js` and `build-min.js`
* `test-core-style-system.html`

<a id="ckeditor5/latest/framework/contributing/code-style.html--standard-files">

##### Standard files

Widely used standard files do not obey the above rules:

* `README.md`, `LICENSE.md`, `CONTRIBUTING.md`, `CHANGES.md`
* `.gitignore` and all standard “dot-files”
* `node_modules`

<a id="ckeditor5/latest/framework/contributing/code-style.html--ckeditor-5-custom-eslint-rules">

### CKEditor 5 custom ESLint rules

In addition to the rules provided by ESLint, CKEditor 5 uses a few custom rules described below.

<a id="ckeditor5/latest/framework/contributing/code-style.html--importing-between-packages-ckeditor5-rulesno-relative-imports">

#### Importing between packages: `ckeditor5-rules/no-relative-imports`

While importing modules from the same package, it is allowed to use relative paths, like this:

```
// Assume we edit a file located in the path: `packages/ckeditor5-engine/src/model/model.js`

import Position from './position';
import insertContent from './utils/insertcontent';

```

While importing modules from other packages, it is not allowed to use relative paths, and the import must be done using the package name, like this:

👎 Examples of incorrect code for this rule:

```
// Assume we edit a file located in the path: `packages/ckeditor5-engine/src/model/model.js`

import CKEditorError from '../../../ckeditor5-utils/src/ckeditorerror';

```

Even if the import statement works locally, it will throw an error when developers install packages from npm.

👍 Examples of correct code for this rule:

```
// Assume we edit a file located in the path: `packages/ckeditor5-engine/src/model/model.js`

import { CKEditorError } from 'ckeditor5';

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/7128)

<a id="ckeditor5/latest/framework/contributing/code-style.html--description-of-an-error-ckeditor5-rulesckeditor-error-message">

#### Description of an error: `ckeditor5-rules/ckeditor-error-message`

Each time a new error is created, it needs a description to be displayed on the [error codes](#ckeditor5/latest/support/error-codes.html) page, like this:

👎 Examples of incorrect code for this rule:

```
// Missing the error's description.

throw new CKEditorError( 'ckeditor5-example-error', this );

// ESLint shouldn't expect the definition of the error as it is already described.

throw new CKEditorError( 'editor-wrong-element', this );

```

👍 Examples of correct code for this rule:

```
// This error occurs for the first time in the project, so it needs to be defined.

/**
 * Description of why the error was thrown and how to fix the code.
 *
 * @error ckeditor5-example-error
 */
throw new CKEditorError( 'ckeditor5-example-error', this );

// This error is already described, so we don't need to provide its documentation.
// We need to disable ESLint for checking the rule.
// It is a good practice to include a note that explains where it is described.

// Documented in core/editor/editor.js
// eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
throw new CKEditorError( 'editor-wrong-element', this );

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/7822)

<a id="ckeditor5/latest/framework/contributing/code-style.html--cross-package-imports-ckeditor5-rulesno-cross-package-imports">

#### Cross package imports: `ckeditor5-rules/no-cross-package-imports`

It is allowed to import modules from other packages:

```
import { toArray } from '@ckeditor/ckeditor5-utils';

```

However, some packages cannot import modules from CKEditor 5 as it could lead to code duplication and errors in runtime. Hence, the rule disables this kind of import.

Currently, it applies to the `@ckeditor/ckeditor5-watchdog` package.

👎 Examples of incorrect code for this rule:

```
// Assume we edit a file located in the `packages/ckeditor5-watchdog/` directory.

import { toArray } from '@ckeditor/ckeditor5-utils';
import { toArray } from 'ckeditor5';

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/9318)

<a id="ckeditor5/latest/framework/contributing/code-style.html--importing-modules-in-debug-comments-ckeditor5-rulesuse-require-for-debug-mode-imports">

#### Importing modules in debug comments: `ckeditor5-rules/use-require-for-debug-mode-imports`

The debug mode allows importing additional modules for testing purposes. Unfortunately, the debug comment is not removed, so webpack reports the following error.

```
Module parse failed: 'import' and 'export' may only appear at the top level (15204:20)
File was processed with these loaders:
 * ./node_modules/@ckeditor/ckeditor5-dev-tests/lib/utils/ck-debug-loader.js
You may need an additional loader to handle the result of these loaders.
|  */
|
> /* @if CK_DEBUG */  import { CKEditorError } from '@ckeditor/ckeditor5-utils';
|
| /**

```

Modules need to be imported with a `require()` function.

To create a code executed only in the debug mode, follow the description of the `--debug` flag in the [testing environment](#ckeditor5/latest/framework/contributing/testing-environment.html--running-manual-tests) guide.

👎 Examples of incorrect code for this rule:

```
// @if CK_DEBUG // import defaultExport from 'module-name';
// @if CK_DEBUG // import * as name from 'module-name';
// @if CK_DEBUG // import { testFunction } from 'module-name';
// @if CK_DEBUG // import { default as alias } from 'module-name';
// @if CK_DEBUG // import { exported as alias } from 'module-name';
// @if CK_DEBUG // import 'module-name';

```

👍 Examples of correct code for this rule:

```
// @if CK_DEBUG // const defaultExport = require( 'module-name' ).default;
// @if CK_DEBUG // const name = require( 'module-name' );
// @if CK_DEBUG // const { testFunction } = require( 'module-name' );
// @if CK_DEBUG // const alias = require( 'module-name' ).default;
// @if CK_DEBUG // const { exported: alias } = require( 'module-name' );
// @if CK_DEBUG // require( 'module-name' );

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/12479)

<a id="ckeditor5/latest/framework/contributing/code-style.html--non-public-members-marked-as-internal-ckeditor5-rulesnon-public-members-as-internal">

#### Non-public members marked as @internal : `ckeditor5-rules/non-public-members-as-internal`

To remove non-public members from type definitions, use the `@internal` tag in the member’s JSDoc.

Then you can use the `"stripInternal": true` option in `tsconfig.json` to remove them from declaration types.

👎 Examples of incorrect code for this rule:

```
class ClassWithSecrets {
    private _shouldNotBeEmitted: string;
}

```

👍 Examples of correct code for this rule:

```
class ClassWithSecrets {
    /**
    * @internal
    */
    private _shouldNotBeEmitted: string;
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--declaring-module-augmentation-for-the-core-package-ckeditor5-rulesallow-declare-module-only-in-augmentation-file">

#### Declaring module augmentation for the core package: `ckeditor5-rules/allow-declare-module-only-in-augmentation-file`

The main entry points (`index.ts` files) in most modules have a side effect import `import './augmentation'` which uses module augmentation to populate the editor types with information about available plugins, configurations and commands.

This rule forces all `declare module '@ckeditor/ckeditor5-core'` to be defined in this `augmentation.ts` file.

<a id="ckeditor5/latest/framework/contributing/code-style.html--importing-from-modules-ckeditor5-rulesallow-imports-only-from-main-package-entry-point">

#### Importing from modules: `ckeditor5-rules/allow-imports-only-from-main-package-entry-point`

This rule ensures that all imports from the `@ckeditor/*` packages are done through the main package entry points. This is required for the editor types to work properly and to ease migration to the installation methods introduced in CKEditor 5 v42.0.0.

👎 Example of incorrect code for this rule:

```
// Importing from the `/src/` folder is not allowed.
import Table from '@ckeditor/ckeditor5-table/src/table';

// Importing from the `/theme/` folder is not allowed.
import BoldIcon from '@ckeditor/ckeditor5-icons/theme/icons/bold.svg';

```

👍 Examples of correct code for this rule:

```
// ✔️ Importing from the main entry point is allowed.
import { Table } from 'ckeditor5';

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--require-as-const-ckeditor5-rulesrequire-as-const-returns-in-methods">

#### Require `as const`: `ckeditor5-rules/require-as-const-returns-in-methods`

In TypeScript, the types inferred from some values are simplified. For example, the type of `const test = [1, 2, 3];` is `number[]`, but in some cases a more specific type may be needed. Using `as const` can help with this. For example, the type of `const test1 = [1, 2, 3] as const;` is `readonly [1, 2, 3]`.

The `require-as-const-returns-in-methods` rule requires some methods that depend on the exact type of returned data (for example, `'delete'` literal string instead of the generic `string` in the `pluginName` method, or `readonly [typeof Table]` instead of `[]` in the `requires` method) to have all return statements with `as const`.

👎 Examples of incorrect code for this rule:

```
export default class Delete extends Plugin {
    public static get pluginName(): string {
        return 'Delete';
    }
}

```

```
export default class Delete extends Plugin {
    public static get pluginName(): 'Delete' {
        return 'Delete';
    }
}

```

👍 Examples of correct code for this rule:

```
export default class Delete extends Plugin {
    public static get pluginName() {
        return 'Delete' as const;
    }
}

```

<a id="ckeditor5/latest/framework/contributing/code-style.html--imports-within-a-package-ckeditor5-rulesno-scoped-imports-within-package">

#### Imports within a package: `ckeditor5-rules/no-scoped-imports-within-package`

All imports defined in every package, that point to a file from the same package, must be relative. You cannot use the scoped imports, if the target file is located in the same package as the import declaration. The resolved scoped import points to the package inside the `node_modules`, but not to the current working directory, and the source code in these two places may differ from each other.

👎 Examples of incorrect code for this rule:

```
// Assume we edit a file located in the path: `packages/ckeditor5-alignment/src/alignment.ts`.

// Both imports are incorrect.
import { AlignmentEditing } from '@ckeditor/ckeditor5-alignment';
import AlignmentEditing from '@ckeditor/ckeditor5-alignment/src/alignmentediting';

```

👍 Examples of correct code for this rule:

```
// Assume we edit a file located in the path: `packages/ckeditor5-alignment/src/alignment.ts`.

import AlignmentEditing from './alignmentediting';

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/14329)

<a id="ckeditor5/latest/framework/contributing/code-style.html--mandatory-file-extensions-in-imports-ckeditor5-rulesrequire-file-extensions-in-imports">

#### Mandatory file extensions in imports: `ckeditor5-rules/require-file-extensions-in-imports`

As required by the [ECMAScript (ESM)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) standard, all imports and re-exports must include a file extension. If they do not include it, this rule will try to automatically detect the correct file extension. It is impossible in these two cases:

* The file extension is different that `.ts`, `.js`, or `.json`.
* The file does not exist in the file system.

The second case is common for the documentation files, because its pieces are located in different directories and repositories. These pieces are merged during the build step, but before that, the imports are technically invalid.

In such cases, you must add the file extension manually. Imports with file extensions are not validated.

<a id="ckeditor5/latest/framework/contributing/code-style.html--require-or-disallow-certain-plugin-flags-ckeditor5-rulesckeditor-plugin-flags">

#### Require or disallow certain plugin flags: `ckeditor5-rules/ckeditor-plugin-flags`

This rule ensures that plugin flags are either correctly set or not set at all. It checks whether the flags have the correct type and value, preventing common mistakes and ensuring compliance with the CKEditor 5 plugin API.

Options:

* `requiredFlags` – (optional) An array of flags that must be set in the plugin.
* `disallowedFlags` – (optional) An array of flags that must not be set in the plugin.

The example configuration below requires the `isFooPlugin` flag to be set to `true` and disallows the `isBarPlugin` flag:

```
{
    "requiredFlags": [
        {
            "name": "isFooPlugin",
            "returnValue": true
        }
    ],
    "disallowedFlags": [ "isBarPlugin" ]
}

```

👎 Examples of incorrect code for this rule:

```
export default class MyPlugin extends Plugin {
    static get pluginName() {
        return 'MyPlugin';
    }

    public static override get isBarPlugin(): false {
        return false;
    }
}

```

The `isBarPlugin` flag is disallowed, and the plugin has it set to `false`. Additionally, the `isFooPlugin` flag is required but not defined.

👍 Examples of correct code for this rule:

```
export default class MyPlugin extends Plugin {
    static get pluginName() {
        return 'MyPlugin';
    }

    public static override get isFooPlugin(): true {
        return true;
    }
}

```

The `isFooPlugin` flag is required and set to `true`, and the `isBarPlugin` flag is not defined.

<a id="ckeditor5/latest/framework/contributing/code-style.html--svg-imports-only-in-the-ckeditorckeditor5-icons-package">

#### SVG imports only in the `@ckeditor/ckeditor5-icons` package

This rule ensures that SVG files are imported and exported only in the `@ckeditor/ckeditor5-icons` package. This package should include all icons used in CKEditor 5.

<a id="ckeditor5/latest/framework/contributing/code-style.html--valid-changelog-entries">

#### Valid changelog entries

This rule ensures that changelog entry files are populated with proper data and a clear description of the change. For a full guide on how to populate changelog entries, see the [Changelog entries](#ckeditor5/latest/framework/contributing/changelog-entries.html) guide.

<a id="ckeditor5/latest/framework/contributing/code-style.html--ckeditor-5-custom-stylelint-rules">

### CKEditor 5 custom Stylelint rules

In addition to the rules provided by Stylelint, CKEditor 5 uses a few custom rules described below.

<a id="ckeditor5/latest/framework/contributing/code-style.html--names-of-css-variables-within-ck-content-ckeditor5-rulesck-content-variable-name">

#### Names of CSS variables within `.ck-content`: `ckeditor5-rules/ck-content-variable-name`

This rule aims to enforce convention of all variables targeting styling of elements within the editor (`.ck-content`) using a common prefix (`--ck-content-*`)

👎 Example of incorrect code for this rule:

```
.ck-content {
    width: var(--variable-name);
}

```

👍 Example of correct code for this rule:

```
.ck-content {
    width: var(--ck-content-variable-name);
}

```

[History of the change.](https://github.com/ckeditor/ckeditor5/issues/18805)

<a id="ckeditor5/latest/framework/contributing/contributing.html">source file: "ckeditor5/latest/framework/contributing/contributing.html"</a>

## Contributing

CKEditor 5 is an Open Source project and we will be most thankful for your contributions. You can help us by fixing issues, reporting them, or translating the editor interface. Community effort and engagement is what has been driving the development of our WYSIWYG editor projects since 2003!

<a id="ckeditor5/latest/framework/contributing/contributing.html--fixing-issues-and-coding-features">

### Fixing issues and coding features

Before you start, here are some things to keep in mind:

* We expect contributions to follow the high-quality code standards that we follow, including [coding style](#ckeditor5/latest/framework/contributing/contributing.html--code-style) and [tests](#ckeditor5/latest/framework/contributing/contributing.html--tests). Lack of attention to this point may either make it slow to adopt a contribution or even force us to reject it altogether.
* There is no guarantee that your contribution will be incorporated into the project code. Still, pull requests make it easy for you to keep them for your own use or for others who may be interested in them.
* If you plan to start working on a bigger task, it might be worth asking the core team (beforehand) whether a specific feature or a solution to an issue will be accepted.
* If you need any assistance when creating a patch or implementing a feature, ping us under the ticket.
* [Having a CLA](#ckeditor5/latest/framework/contributing/contributing.html--contributor-license-agreement-cla) is essential to have your contributions accepted.

<a id="ckeditor5/latest/framework/contributing/contributing.html--setting-up-the-development-environment">

#### Setting up the development environment

To learn how to set up the project and run tests see the [development environment](#ckeditor5/latest/framework/contributing/development-environment.html) guide.

<a id="ckeditor5/latest/framework/contributing/contributing.html--code-style">

#### Code style

Read more in the [code style](#ckeditor5/latest/framework/contributing/code-style.html) guide, where you can also check the [naming](#ckeditor5/latest/framework/contributing/code-style.html--naming) and [file name](#ckeditor5/latest/framework/contributing/code-style.html--file-names) guidelines.

Every package repository installs Git hooks that automatically lint and check the code for code style on commit. However, not every code style issue can be discovered this way, so please do not rely on tools too much.

<a id="ckeditor5/latest/framework/contributing/contributing.html--tests">

#### Tests

We maintain a **100% code coverage** (including code branches) and pull requests with missing tests will not be accepted. However, keep in mind that 100% is not everything – every _change_ must be tested. This means that if you are fixing a bug and your patch did not change the code coverage, the change itself needs a test anyway.

Besides automated tests, you may be asked to create a manual test for the issue. Such manual tests let us quickly validate that the issue was really fixed and are later used during the testing phase (before a release) to make sure no regressions were created.

Read more about our [testing environment](#ckeditor5/latest/framework/contributing/testing-environment.html).

<a id="ckeditor5/latest/framework/contributing/contributing.html--creating-a-pull-request">

#### Creating a pull request

Assuming that you would like to propose some changes, these are the steps you should take to create a pull request:

1. Make sure to open a ticket in <https://github.com/ckeditor/ckeditor5> describing the issue, feature or problem that you want to solve in your pull request. This can be skipped in case of obvious and trivial changes (typos, documentation, etc.).
2. Make sure your [development environment](#ckeditor5/latest/framework/contributing/development-environment.html) is ready.
3. Go to GitHub and [fork the repository](https://help.github.com/articles/fork-a-repo). The forked repository will appear in your GitHub account as `https://github.com/YOUR-USERNAME/ckeditor5`.
4. Open your terminal, then go to the package (“repository”) folder in your development environment:  
```  
$ cd path/to/ckeditor5  
```
5. Start a new branch for your code. We use the `i/GITHUB-ISSUE-NUMBER` convention for branch names:  
```  
$ git checkout -b i/GITHUB-ISSUE-NUMBER  
```
6. Make the changes. Stick to the [code-style guidelines](#ckeditor5/latest/framework/contributing/contributing.html--code-style) and remember about [tests and 100% code coverage](#ckeditor5/latest/framework/contributing/contributing.html--tests)!
7. Commit your changes:  
```  
$ git commit -m "Squashed a nasty bug in the link editing."  
```
8. Now it is time to make your changes public. First, you need to let `git` know about the fork you created by adding the remote:  
```  
$ git remote add my-fork https://github.com/YOUR-USERNAME/ckeditor5  
```
9. Push your changes to your forked repository:  
```  
$ git push my-fork i/GITHUB-ISSUE-NUMBER  
```
10. Go to your forked repository on GitHub. Use the [pull request button](https://help.github.com/articles/about-pull-requests/) and follow the instructions.
11. **Let us know about your pull request!** The best way is to comment under the original issue.

Some additional things you should keep in mind:

* Your pull request should be minimal. It should change only things described in the ticket. Do not squeeze unrelated changes into your pull request.
* When making a pull request on GitHub, make sure to specify which ticket(s) your pull request resolves. It is also recommended to provide more information, like how to test the patch, issues that you encountered, decisions you had to make, known problems, etc.
* Make sure you signed the [Contributor License Agreement (CLA)](#ckeditor5/latest/framework/contributing/contributing.html--contributor-license-agreement-cla) and that tests pass. Test your changes!

<a id="ckeditor5/latest/framework/contributing/contributing.html--translating">

### Translating

CKEditor 5 is a project with global impact, so contributing translations is both an easy and powerful way to help.

To make CKEditor 5 available in multiple languages, we use `.po` files for storing translations. These are text files commonly used in software development to translate interface texts. Each CKEditor 5 package keeps translation files in the `lang/translations` directory. To provide missing translations, just edit the `.po` file and prepare a [pull request](#ckeditor5/latest/framework/contributing/contributing.html--creating-a-pull-request).

Here as well, having a CLA in place is a requirement to become an official translator (see below).

<a id="ckeditor5/latest/framework/contributing/contributing.html--reporting-issues-and-requesting-features">

### Reporting issues and requesting features

Read the [reporting issues](#ckeditor5/latest/support/index.html--reporting-issues) guide to learn more.

<a id="ckeditor5/latest/framework/contributing/contributing.html--contributor-license-agreement-cla">

### Contributor License Agreement (CLA)

To accept contributions sent to us in the form of code, documentation, or translations, a Contributor License Agreement (CLA) must be in place to clarify the intellectual property license granted with them. This license is for your protection as a contributor as well as the protection of us and our users; it does not change your rights to use your own contributions for any other purpose.

To sign the CLA and to get more information, follow this link: <https://cla.ckeditor.com/>.

<a id="ckeditor5/latest/framework/contributing/contributing.html--signing-commits">

### Signing commits

Starting January 1, 2025, all commits targeting the main branches must be signed for security reasons. We therefore require you to sign all commits added to CKEditor 5’s codebase.

We use Git signing to ensure the commits added to the codebase are verified. By signing your commits, you can prove that you are the author and ensure that the code has not been tampered with. This aids the compliance with our SOC2 Type 2 certification.

Git commit signing attaches a unique cryptographic signature to a commit, which adds a layer of security, making it easier to trust the source of the code changes. To set up your digital signature, please refer to the GitHub [Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) guide. Please note that the GPG key must use the same values as a committer, so the name, surname, and email must be identical.

<a id="ckeditor5/latest/framework/contributing/development-environment.html">source file: "ckeditor5/latest/framework/contributing/development-environment.html"</a>

## Development environment

The CKEditor 5 codebase is divided into multiple [npm](http://npmjs.com/) packages. The main package is [ckeditor5](https://github.com/ckeditor/ckeditor5) which installs all project dependencies and various development-related resources such as:

* the testing environment setup,
* configuration for [pnpm](https://pnpm.io),
* translation management tools,
* documentation generator,
* and release tools.

The main package’s GitHub repository also [hosts all other CKEditor5 sub-packages](https://github.com/ckeditor/ckeditor5/tree/master/packages).

You can find all the official packages listed in the [CKEditor 5 repository’s README](https://github.com/ckeditor/ckeditor5#packages).

<a id="ckeditor5/latest/framework/contributing/development-environment.html--requirements">

### Requirements

To start developing CKEditor 5 you will require:

* [Node.js](https://nodejs.org/en/) 24.11.0+
* [pnpm](https://pnpm.io/) 10.17.0+
* [Git](https://git-scm.com/)

<a id="ckeditor5/latest/framework/contributing/development-environment.html--setting-up-the-ckeditor-development-environment">

### Setting up the CKEditor development environment

First, you need to install [pnpm](https://pnpm.io) to use it for dependency management.

It is best to install it in your system is to [follow the official pnpm installation guide](https://pnpm.io/installation).

Then clone the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5):

```
git clone https://github.com/ckeditor/ckeditor5.git
cd ckeditor5

```

And install all CKEditor 5 packages from the [npm registry](http://npmjs.com/).

```
pnpm install

```

<a id="ckeditor5/latest/framework/contributing/development-environment.html--running-tests">

### Running tests

To run tests, you need to use the `test` and `manual` tasks.

```
pnpm run test --watch --coverage --source-map --files=engine

```

or, shorter:

```
pnpm run test -- -wcs --files=engine

```

This command will run the [ckeditor5-engine](https://github.com/ckeditor/ckeditor5-engine) package’s tests.

**Note:** It is not possible to run tests of all packages with code coverage at once because the size of the project (the number of test files and source modules) exceeds webpack’s capabilities (it runs out of memory).

To create a server for manual tests use the `manual` task:

```
pnpm run manual

```

To help test localized editors, the task accepts two optional configurations: `--language="en"` and `--additionalLanguages="ar,pl,..."`. The former sets the main language used by test editors. By default it is `"en"` and in most scenarios, you do not need to change it. The latter brings more languages to manual tests, which is helpful for example,when working with [right–to–left languages in the user interface](#ckeditor5/latest/getting-started/setup/ui-language.html--righttoleft-rtl-languages-support).

You can read more about the [Testing environment](#ckeditor5/latest/framework/contributing/testing-environment.html).

<a id="ckeditor5/latest/framework/contributing/development-environment.html--generating-documentation">

### Generating documentation

To build the documentation, you need to run the `docs` task:

```
pnpm run docs

```

The documentation will be available in `build/docs/`.

This task accepts the following arguments:

* `--skip-api` – Skips building the API documentation (which takes the majority of the total time).
* `--skip-snippets` – Skips building live snippets.
* `--skip-validation` – Skips the final link validation.
* `--skip-guides` – Skips building all guides except the `index.md` files which allows navigating over the partially built documentation.
* `--guides=guide-name` – Guides to build. Accepts glob patterns that are matched against guide names. Examples:  
```
--guides=image         // matches roughly "*image*"
--guides="features/*"  // matches roughly "*features/*"
--guides=features/image  
```
* `--watch` – Runs the documentation generator in a watch mode. It covers guides but it does not cover API docs.
* `--production` – Minifies the assets and performs other actions which are unnecessary during CKEditor 5 development.
* `--verbose` – Prints out more information.

```
pnpm run docs --skip-api

```

After building documentation, you can quickly start an HTTP server to serve them:

```
pnpm run docs:serve

```

<a id="ckeditor5/latest/framework/contributing/development-environment.html--verifying-documentation">

#### Verifying documentation

To verify that all pages in our documentation can be opened without any errors, you do not need to do that manually, page by page. Instead, there is a web crawler that automatically traverses the documentation and it visits all pages that have been found. The crawler opens a headless Chromium browser and logs to the console any error that has been found.

To check pages in the documentation, build it (`pnpm run docs`), serve it (`pnpm run docs:serve`), and then run the crawler:

```
pnpm run docs:verify

```

The crawler collects and opens all links from the documentation, except the API and assets.

The crawler accepts the following arguments:

* `--url` (alias `-u`) – The URL to start crawling. This argument is required. Thanks to it you can verify for example,a deployed documentation.
* `--depth` (alias `-d`) – A number that defines how many nested page levels should be examined. Infinity by default.
* `--exclude` (alias `-e`) – A string with URL exclusion – links that match the excluded part are skipped. You can define multiple exclusions by providing multiple `--exclude` (or `-e`) arguments. Not specifying a value removes default exclusions, if any. Nothing is excluded by default, but the `docs:verify` script has some predefined ones.
* `--concurrency` (alias `-c`) – Number of concurrent pages (browser tabs) to be used during the scan. By default all links are opened one by one, sequentially (concurrency is 1).
* `--quit` (alias `-q`) – A boolean argument that specifies, whether the scan should be terminated as soon as the first error is found. Disabled by default, so all found links are scanned regardless of whether they have errors or not.

For example, to check the documentation without the default exclusions (the API and assets links), using only 2 concurrent pages and terminate the scan as soon as first error is found, run this command:

```
pnpm run docs:verify -e -c 2 -q

```

<a id="ckeditor5/latest/framework/contributing/development-environment.html--defining-exclusions-for-web-crawler">

##### Defining exclusions for web crawler

The crawler supports exclusions provided as text patterns, which are then searched for in the error messages as substrings. This pattern is just a plain text, not a regular expression. When a pattern (substring) is found, such an error is ignored - it is not listed after the finished scan and it does not mark the entire scan as failed. Only non-ignored errors are logged at the end of the scan.

The pattern for ignoring an error must be defined in `<meta>` tag on a page, where an error occurs. This `<meta>` tag must have `x-cke-crawler-ignore-patterns` name and `content` value provided as JSON object, where:

* Each key is the error type, that can be detected by the crawler.
* Each value is the text or an array of texts, that are used for finding a match in error messages. The special wildcard value `*` can be used to ignore all errors for a given error type.

The following error types are supported: `uncaught-exception`, `request-failure`, `response-failure`, `console-error`, `navigation-error` and `page-crash`:

* `uncaught-exception` – As the name suggests, these are uncaught exceptions from the page.
* `request-failure` – This error occurs, when the request has not been sent (for example, it was blocked by the browser) or has not received any response (for example, due to a timeout or in case the remote server is unreachable). HTTP error responses, such as 404 or 500, are considered successful ones from the HTTP standpoint. Such requests will not be logged as request failures but as response failures.
* `response-failure` – Each HTTP response with a status code equal to or greater than 400 is treated as a failed one.
* `console-error` – All `console.error()` calls are treated as an error.
* `navigation-error` – The navigation error may happen, when:  
  * There is an SSL error (for example,in the case of a self-signed certificate or an expired one).
  * The target URL is invalid.
  * The timeout is exceeded during navigation to a page, so the `load` event is not emitted (for example, due to an infinite loop in the JavaScript code).
* `page-crash` – The general page malfunction, that does not fit other categories (like running out of RAM).

| Error type         | Example                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| uncaught-exception | "uncaught-exception": "ckeditor-duplicated-modules" This pattern ignores only the ckeditor-duplicated-modules exception. |
| request-failure    | "request-failure": "missing-file.jpg" All requests containing the missing-file.jpg in the URL are ignored.               |
| response-failure   | "response-failure": "HTTP response status code: 401" All requests requiring authorization are ignored.                   |
| console-error      | "console-error": "Example error message" All console errors containing “Example error message” substring are ignored.    |
| navigation-error   | "navigation-error": "Navigation timeout of 15000 ms exceeded" Links, which are not completely loaded, are ignored.       |
| page-crash         | "page-crash": "Error: Page crashed!" This general text pattern ignores all page crashes.                                 |

These patterns are simply added as keys and values in a JSON object to the `<meta>` tag on a page, where they should be active:

```
<meta name="x-cke-crawler-ignore-patterns" content='{
    "page-crash": "Error: Page crashed!",
    "uncaught-exception": "ckeditor-duplicated-modules",
    "console-error": "Example error message"
}'>

```

The pattern (regardless of the type of error) does not have to be a string, but can also be defined as an array of strings (patterns) to ignore many different errors:

```
<meta name="x-cke-crawler-ignore-patterns" content='{
    "console-error": [ "Error 1", "Error 2", "Error 3" ]
}'>

```

To ignore all errors, use the special wildcard value `*`:

```
<meta name="x-cke-crawler-ignore-patterns" content='{
    "console-error": "*"
}'>

```

In addition to the possibility of defining exclusions in the `<meta>` tag, it is also possible to specify that the link cannot be visited by the crawler by adding a `data-cke-crawler-skip` attribute:

```
<a href="path/to/page" data-cke-crawler-skip>No entry for crawler, sorry</a>

```

<a id="ckeditor5/latest/framework/contributing/development-environment.html--generating-content-styles">

### Generating content styles

Content styles let you customize the appearance of editor content presented to the readers.

For a complete explanation of what content styles are, how they work, and how to configure them in your project, refer to the [Content styles](#ckeditor5/latest/getting-started/setup/css.html) guide.

<a id="ckeditor5/latest/framework/contributing/development-environment.html--additional-information-for-contributors">

### Additional information for contributors

<a id="ckeditor5/latest/framework/contributing/development-environment.html--svg-icons">

#### SVG icons

By default, CKEditor 5 supports SVG icons found in the `ckeditor5-*/theme/icons` folders. Unfortunately, most of the SVG editing software produces the output with comments, obsolete tags, and complex paths, which bloats the DOM and makes the builds heavy for no good reason.

To remove the excess data and prevent [certain issues](https://github.com/ckeditor/ckeditor5-ui/issues/245), **you should optimize all new icons before adding them to the code base**. To do that, you can use the `clean-up-svg-icons` script in the [root of the project](#ckeditor5/latest/framework/contributing/development-environment.html--setting-up-the-ckeditor-development-environment), a wrapper for the [SVGO](https://github.com/svg/svgo) tool:

```
cd path/to/ckeditor5

# Optimize all SVG files in the folder.
npm run clean-up-svg-icons path/to/icons/*.svg

# Optimize a single SVG file.
npm run clean-up-svg-icons path/to/icon/icon.svg

```

The script reduces the icon size up to 70%, depending on the software used to create it and the general complexity of the image.

<a id="ckeditor5/latest/framework/contributing/package-metadata.html">source file: "ckeditor5/latest/framework/contributing/package-metadata.html"</a>

## Package metadata

The package metadata is a set of CKEditor 5-related data describing plugins that the package delivers. It allows for the automated detection of plugins and building them by an external builder.

In the case of official CKEditor 5 packages (as well as some partner ones), this data is used by the [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) and allows for building the [Features’ HTML output](#ckeditor5/latest/framework/architecture/plugins.html--plugins-and-html-output) page presenting a list of all official CKEditor 5 plugins.

The package metadata should be saved in the special `ckeditor5-metadata.json` file in the root of the package published on npm.

<a id="ckeditor5/latest/framework/contributing/package-metadata.html--data-format-for-plugin-metadata">

### Data format for plugin metadata

The `ckeditor5-metadata.json` file is a JSON object that holds the `plugins` array. Each element of this array should be an object containing information about a different plugin delivered by the package. Below is a list of all metadata properties that can be used to describe a plugin:

* `name` – A human-readable name of the plugin.
* `description` – A human-readable short description of the plugin.
* `docs` – An absolute or relative URL to the plugin documentation. If this URL is relative, it leads to the CKEditor 5 documentation in [https://ckeditor.com/docs/ckeditor5/latest/](#ckeditor5/latest/index.html).
* `path` – A path to the file, relative to the metadata file that exports the plugin.
* `className` – The name of the class used to create the plugin. This class should be exported from the file using the `export default` syntax.
* `requires` – An array of the plugin’s soft requirements and other non-explicit requirements. It should contain class names of plugins that should be included if this plugin is added. If the element of this array is another (nested) array containing plugins’ class names, it means that at least one plugin listed from this nested array is required, but not all of them.
* `registeredToolbars` – An array of all toolbar names registered by the plugin. These names need to represent the configuration path (for example, `table.contentToolbar` for `editorConfig.table.contentToolbar` and `table.tableToolbar` for the `editorConfig.table.tableToolbar`, which are registered by the `Table` plugin).
* `uiComponents` – An array of objects that describes UI components exported by the plugin. Each object in this array may contain:  
  * `name` – The name of the component the plugin exports. It should match the actual UI name registered by the plugin.
  * `type` – The component type: `Button`, `SplitButton` or `Dropdown`.
  * `iconName` – The exported icon identifier from `@ckeditor/ckeditor5-icons` (for example, `IconBold`, `IconTable`). Must match an export name from the icons package.
  * `label` – Text content for `Dropdown` components.
  * `toolbars` – An array of toolbar names that a given UI component can be added to. Some UI components may be added to multiple toolbars.
* `htmlOutput` – An array of objects that defines all possible HTML elements which can be created by a given plugin. The main property in this object is `elements`. Other properties (like `classes`, `styles`, `attributes`) only apply to items defined in the `elements` property within a given object. The wildcard character `*` is used to mark any value. The full list of all these properties includes:  
  * `elements` – HTML elements (a single one or an array of these) that are created or altered by the plugin. The pseudo-element `$block` indicates that a given plugin applies classes, styles or attributes (defined in appropriate properties) for all block elements.
  * `classes` – CSS class names (a single one or an array of these) that may be applied to the HTML elements defined in the `elements` property.
  * `styles` – Inline CSS styles (a single one or an array of these) that may be applied to the HTML elements defined in the `elements` property.
  * `attributes` – HTML attributes (a single one or an array of these) other than `class` and `styles` (covered separately) that might be applied to the HTML elements defined in the `elements` property.
  * `implements` – The name of an element or a pseudo-element which indicates that HTML elements defined in the `elements` property may contain classes, styles or attributes that are created by other plugins. For example, `implements` equal to `$block` means that HTML elements may contain classes, styles or attributes that are defined by another plugin, which has `elements` equal to `$block`.
  * `isAlternative` – If the plugin output depends on its configuration, this value should be set to `true` to mark outputs that are not produced by the default configuration. If this value is either missing or `false`, the output will be considered as default output.
  * `_comment` – A human-readable description to explain more complicated cases, for example: the conditions when a given element, class or style can be created.

Below is an example showing how the `Bold` plugin can be documented using this format:

```
{
    "name": "Bold",
    "className": "Bold",
    "description": "Implements bold formatting support. It is a part of the basic text styles package.",
    "docs": "features/basic-styles.html",
    "path": "src/bold.js",
    "uiComponents": [
        {
            "type": "Button",
            "name": "bold",
            "iconName": "IconBold"
        }
    ],
    "htmlOutput": [
        {
            "elements": "strong"
        }
    ]
}

```

If you want to check how plugins are documented in other packages, visit the [CKEditor 5 packages](https://github.com/ckeditor/ckeditor5/tree/master/packages) section on GitHub and find the `ckeditor5-metadata.json` file in a package you are interested in.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html">source file: "ckeditor5/latest/framework/contributing/testing-environment.html"</a>

## Testing environment

Before reading this article we recommend getting familiar with the CKEditor 5 [development environment](#ckeditor5/latest/framework/contributing/development-environment.html).

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--introduction">

### Introduction

The CKEditor 5 testing environment uses a popular setup with [Karma](https://karma-runner.github.io), [webpack](https://webpack.github.io/), [babel-loader](https://github.com/babel/babel-loader) and [Istanbul](https://github.com/gotwarlost/istanbul). We created some [npm scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts) which glue all these pieces and special requirements for CKEditor together.

Each CKEditor 5 package has its own tests suite (see for example the [engine’s tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests)). However, the test runner is available in the root of the [ckeditor5](https://github.com/ckeditor/ckeditor5) repository which is the central development environment. The actual code of the test runner is implemented in the [@ckeditor/ckeditor5-dev-tests](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-tests) package and can be reused outside of `ckeditor5`.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--running-automated-tests">

### Running automated tests

To run the automated tests, use the `pnpm run test [<args>...]` command.

It accepts the following arguments (you can also run with `--help` to see all available options):

* `--watch` (alias `-w`) – Whether to watch the files and execute tests whenever any file changes.
* `--source-map` (alias `-s`) – Whether to generate useful source maps for the code.
* `--coverage` (alias `-c`) – Whether to generate code coverage.
* `--verbose` (alias `-v`) – Allows switching on webpack logs.
* `--files` – Specifies test files to run. See the [Rules for using the \--files option](#ckeditor5/latest/framework/contributing/testing-environment.html--rules-for-using-the-files-option) section.
* `--browsers` – Browsers that will be used to run the tests. Defaults to `Chrome`.
* `--port` – Specifies the port for the server to use. Defaults to `9876`.
* `--identity-file="/path/to/file.js"` (alias `-i`) – Path to the file containing the license key(s) for closed–source features.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--examples">

#### Examples

Run all tests with the code coverage check of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package:

```
pnpm run test -c --files=core

```

Run and watch with the code coverage check the [engine’s view namespace tests](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests/view) and all the tests in [ckeditor5-typing](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-typing/tests):

```
pnpm run test -cw --files=engine/view/,typing

```

Run and watch the `bold*.js` tests in the [ckeditor5-basic-styles](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles/tests) package:

```
pnpm run test -w --files=basic-styles/bold*

```

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--custom-chai-assertions">

#### Custom Chai assertions

The testing environment allows for some custom `Chai` assertions. There is no need to import them, as they are imported by default inside all tests.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--equalmarkup">

##### `equalMarkup`

Tests whether two given strings containing markup language are equal. Unlike `expect().to.equal()` from the Chai assertion library, this assertion formats the markup before showing a diff. It can be used to test HTML strings and strings containing a serialized model.

This assertion will pass:

```
expect( `<b>foo</b>` ).to.equalMarkup( `<b>foo</b>` )

```

This assertion will throw an error:

```
expect(
    '<paragraph>foo bXXX[]r baz</paragraph>'
).to.equalMarkup(
    '<paragraph>foo bYYY[]r baz</paragraph>'
);

```

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--attribute">

##### `attribute`

Asserts that the target has an attribute with the given key name. See [hasAttribute](../../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html#function-hasAttribute).

```
expect( selection ).to.have.attribute( 'linkHref' );

```

When an optional `value` is provided, `.attribute` also asserts that the attribute’s value is equal to the given `value`. See [getAttribute](../../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html#function-getAttribute).

```
expect( selection ).to.have.attribute( 'linkHref', 'example.com' );

```

Negations work as well.

```
expect( selection ).to.not.have.attribute( 'linkHref' );

```

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--running-manual-tests">

### Running manual tests

To start the manual tests server, use the `pnpm run manual` task.

The `pnpm run manual` task accepts the following options (you can also run with `--help` to see all available options):

* `--files` – Specifies test files to run. See the [Rules for using the \--files option](#ckeditor5/latest/framework/contributing/testing-environment.html--rules-for-using-the-files-option) section.
* `--language="pl"` – The main language built into all test editors, passed to the [CKEditor 5 translations plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-translations). Check out the [UI language guide](#ckeditor5/latest/getting-started/setup/ui-language.html) to learn more. If unspecified, `'en'` is passed to the test runner.
* `--additional-languages="ar,pl,..."` – Specifies extra languages passed to the [CKEditor 5 translations plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-translations). Check out the [UI language guide](#ckeditor5/latest/getting-started/setup/ui-language.html) to learn more.
* `--debug` (alias `-d`) – Allows specifying custom debug flags. For example, the `--debug engine` option uncomments the `// @if CK_DEBUG_ENGINE //` lines in the code. Note that by default `--debug` is set to `true` even if you did not specify it. This enables the base set of debug logs (`// @if CK_DEBUG //`) which should always be enabled in the testing environment. You can completely turn off the debug mode by setting the `--debug false` option.
* `--port` – Specifies the port for the server to use. Defaults to `8125`.
* `--identity-file="/path/to/file.js"` (alias `-i`) – Path to the file containing the license key(s) for closed–source features.
* `--disable-watch` – It is enabled by default when there are no `--files` specified. This is due to high RAM memory usage when running watchers on all files. Disabling watch mode causes the files to no longer be rebuilt automatically when changed.

It starts the server available at <http://localhost:8125>.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--creating-a-manual-test">

#### Creating a manual test

A manual test consists of 3 files:

* A `<name>.md` file with the test description.
* A `<name>.js` or `<name>.ts` file with the JavaScript or TypeScript part of the test (for example, the code initializing an editor).
* A `<name>.html` file with the HTML part of the test. It does not need to be an entire HTML page (with the DOCTYPE, etc.). It can include just the HTML elements that you want to define.

All 3 files are combined and create a single manual test.

An example Markdown file:

```
## Create a new link

1. Select a fragment of the regular text.
2. Click the toolbar "Link" button.
3. Check if the balloon panel attached to the selection appeared.
4. Fill in the "Link URL" input in the panel.
5. Click the "Save" button.
6. Check if the selected text is converted into a link.

```

An example HTML file:

```
<head>
    <style>
        /*
          Some additional styles which this test needs.
          And yes – the test builder will merge this tag with the head defined in the template.
        */
    </style>
</head>

<div id="editor">...</div>

```

An example JavaScript file:

```
import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Essentials, Paragraph ]
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--verifying-all-manual-tests">

#### Verifying all manual tests

To verify that all manual tests can be **opened** without any errors (the crawler does not execute the manual test steps, it just visits the page), you do not need to do that manually, page by page. Instead, there is a web crawler that automatically traverses the documentation and visits all pages that have been found. The crawler opens a headless Chromium browser and logs to the console any error that has been found.

To check manual tests, start the server (`pnpm manual --files=XYZ`), and then run the crawler:

```
pnpm run manual:verify

```

Read more about the crawler in the [Verifying documentation](#ckeditor5/latest/framework/contributing/development-environment.html--verifying-documentation) guide.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--running-memory-leak-tests">

### Running memory leak tests

To run the memory leak tests, use the `pnpm run test:memory` command. It builds a browser bundle, starts a local server, and runs the tests in headless Chromium.

The command accepts the following arguments:

* `--editor` – A list of editor names to test. You can pass the option multiple times. Defaults to `BalloonEditor`, `ClassicEditor`, `DecoupledEditor`, `InlineEditor`, and `MultiRootEditor`.
* `--html` – The HTML file to load from `scripts/memory/assets`. Defaults to `index.html`.
* `--no-build` – Skips generating the browser build and reuses the existing editor assets.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--examples-2">

#### Examples

Run all memory leak tests:

```
pnpm run test:memory

```

Test only the classic and inline editors:

```
pnpm run test:memory --editor ClassicEditor --editor InlineEditor

```

Use a custom HTML file from `scripts/memory/assets`:

```
pnpm run test:memory --html my-test.html

```

Reuse existing assets:

```
pnpm run test:memory --no-build

```

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--interpreting-the-results">

#### Interpreting the results

Each editor run consists of multiple create/destroy cycles. The warmup phase creates and destroys the editor a few times to populate caches and JIT state. The actual test then repeats the same create/destroy cycle more times while sampling memory between cycles. This makes the results less sensitive to first‑run effects and helps highlight steady growth trends.

After the run completes, the summary table reports:

* **Baseline** – The memory level after warmup. It is the reference point for the rest of the run and should already include initial cache effects.
* **Growth** – The difference between the final measurement and the baseline across repeated cycles. Use this to spot steady memory increases over time rather than one‑off spikes.
* **Tail Growth** – The spread within the last few measurements. It helps verify that memory stabilized near the end; large values suggest a still-growing footprint or high noise even after multiple cycles.
* **Status** – `OK` when both Growth and Tail Growth stay below the threshold. `Exceeds threshold` or `Error` means the run should be treated as a failure.

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--rules-for-using-the-files-option">

### Rules for using the `--files` option

The `--files` (alias `-f`) option is used by both the manual and automated tests. Running tests for the root of the mono-repository is no longer supported. Each set of tests should be assigned to a package, and placed in `tests` directory. It accepts the following types of patterns:

| Patterns                            | Result                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ckeditor5-core                      | Run all tests of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package by specifying the full package name.                                                                                                                                                                                        |
| core                                | Run all tests of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package by specifying a short package name.                                                                                                                                                                                         |
| editor-\*                           | Run all tests of the editor-\* packages. (ckeditor5-editor-classic, ckeditor5-editor-balloon etc.)                                                                                                                                                                                                                                                         |
| !core                               | Run all tests **except** those of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) package.                                                                                                                                                                                                           |
| !(core\|engine)                     | Run all tests **except** those of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests) **and** the [ckeditor5-engine](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests) packages. Any number of packages can be excluded.                                                |
| engine/view/                        | Run all tests of the [ckeditor5-engine](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-engine/tests/view) package located in the ./packages/ckeditor5-engine/tests/view/ directory.                                                                                                                                                  |
| core/editor/utils/                  | Run all tests of the [ckeditor5-core](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-core/tests/editor/utils) package located in the ./packages/ckeditor5-core/tests/editor/utils/ directory.                                                                                                                                        |
| basic-styles/bold                   | Run all tests with the filename bold.js in the [ckeditor5-basic-styles](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles/tests) package.                                                                                                                                                                                  |
| basic-styles/bold\*                 | Run all tests matching the filename pattern bold\*.js in the [ckeditor5-basic-styles](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-basic-styles/tests) package: ./packages/ckeditor5-basic-styles/tests/bold.js ./packages/ckeditor5-basic-styles/tests/bold/boldediting.js ./packages/ckeditor5-basic-styles/tests/bold/boldui.js |
| ckeditor5,list/list/,style/\*grid\* | Sum of all arguments separated by a comma ,. This one can use any combination of argument types. Note that since it is a sum, using multiple !foo excluding arguments might not work as expected.                                                                                                                                                          |

<a id="ckeditor5/latest/framework/contributing/testing-environment.html--test-suite-and-ci">

### Test suite and CI

To ensure the highest quality, we maintain a complete test suite with a stable 100% code coverage for each of the packages. As of September 2019, this means over 11000 tests and the number is growing. Since every package is tested separately, we implement lower-level tests for libraries and higher-level tests for end-user features.

Such an extensive test suite requires a proper continuous integration service. We use [Travis CI](https://travis-ci.com/) as a build platform. This service ensures a seamless and fast developer experience and allows us to focus on the job.

Besides automated tests, we also maintain a smaller set of manual tests. They help us verify whether something unexpected happens that might have been missed by the automated tests.

When proposing a pull request, make sure to add test(s) that verify it. Every code change should be accompanied by a test which proves that it is needed. Such a strict approach to testing ensures that we have not only 100% of code coverage (which is quite easy to achieve and gives only illusory safety) but also a high level of coverage for cases that we failed to notice initially (and might do that again in the future).

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html">source file: "ckeditor5/latest/framework/deep-dive/clipboard.html"</a>

## Clipboard

The clipboard feature (implemented by the [Clipboard](../../api/module%5Fclipboard%5Fclipboard-Clipboard.html) plugin) is responsible for the integration with the native clipboard. The native clipboard is a feature of the operating system and the browser. It is used when the user copies, cuts, pastes, or drags and drops content within the editor or from/to the “outside.”

CKEditor 5 intercepts all native events like `copy`, `cut`, or `drop` and handles them on its side. The goal is to not allow the browser to touch the content in the rich text editor. This could lead to the browser messing it up.

There are two directions of content processing:

* When the content is being pasted or dropped into the editor, it goes through the [input pipeline](#ckeditor5/latest/framework/deep-dive/clipboard.html--input-pipeline).
* When the content is being copied, cut, or dragged from the editor, it goes through the [output pipeline](#ckeditor5/latest/framework/deep-dive/clipboard.html--output-pipeline).

Both pipelines allow the features to process the content to be inserted or set to the clipboard. They also allow to override the default mechanisms at different stages of these processes.

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--input-pipeline">

### Input pipeline

When the user pastes or drops content into the editor, the browser fires an event. The clipboard feature intercepts this event and starts the following mechanism:

1. [ClipboardObserver](../../api/module%5Fclipboard%5Fclipboardobserver-ClipboardObserver.html) turns this event into a synthetic [view.Document#paste](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-paste) or [view.Document#drop](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-drop).
2. The content to be inserted by both actions (paste and drop) should usually be processed in the same way and both actions have a similar effect. Both events are thus turned into a single [view.Document#clipboardInput](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-clipboardInput) event for easier handling.
3. Next, the clipboard feature listens to the `view.Document#clipboardInput` event and retrieves and pre-processes the `text/html` or `text/plain` content which it finds in the [event’s dataTransfer](../../api/module%5Fengine%5Fview%5Fdatatransfer-ViewDataTransfer.html). It then fires the [ClipboardPipeline#inputTransformation](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-inputTransformation) event with the retrieved content in the event data `content` property as a [view.DocumentFragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html).
4. Then, the clipboard feature listens to the `ClipboardPipeline#inputTransformation` event. It takes the processed content and transforms it to the [model.DocumentFragment](../../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html). It then fires the [ClipboardPipeline#contentInsertion](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-contentInsertion) event with the transformed content in the event data `content` property as a [model.DocumentFragment](../../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html).
5. Finally, the clipboard feature listens to the `ClipboardPipeline#contentInsertion` event. It takes the model fragment and [inserts](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) it into the editor. Then it stores the range which contains all the performed changes in the `resultRange` property of the event data.

The clipboard feature listens to the `view.Document#clipboardInput`, `ClipboardPipeline#inputTransformation`, and `ClipboardPipeline#contentInsertion` events using [low priority listeners](#ckeditor5/latest/framework/deep-dive/event-system.html--listener-priorities). This means that adding a normal listener and calling `evt.stop()` allows overriding the behavior implemented by the clipboard feature. It is a similar mechanism to the DOM’s `evt.preventDefault()` that lets you override the default browser behavior.

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--input-pipeline-events-overview">

#### Input pipeline events overview

```
 ┌──────────────────────┐          ┌──────────────────────┐
 │     view.Document    │          │     view.Document    │
 │         paste        │          │         drop         │
 └───────────┬──────────┘          └───────────┬──────────┘
             │                                 │
             └────────────────┌────────────────┘
                              │
                    ┌─────────V────────┐
                    │   view.Document  │   Retrieves text/html from data.dataTransfer
                    │  clipboardInput  │   and processes it to view.DocumentFragment.
                    └─────────┬────────┘
                              │
                  ┌───────────V───────────┐
                  │   ClipboardPipeline   │   Converts view.DocumentFragment
                  │  inputTransformation  │   to model.DocumentFragment.
                  └───────────┬───────────┘
                              │
                   ┌──────────V──────────┐
                   │  ClipboardPipeline  │   Calls model.insertContent().
                   │   contentInsertion  │
                   └─────────────────────┘

```

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--handling-clipboard-input-differently">

#### Handling clipboard input differently

By default, the clipboard feature retrieves `text/html` or `text/plain` from the clipboard. It normalizes the data a bit (for example, cleans up the [mess with whitespaces](https://github.com/ckeditor/ckeditor5-clipboard/issues/2)). It converts it to a [view DocumentFragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html) and fires the `ClipboardPipeline#inputTransformation` event with the document fragment for further processing.

You can use the [view.Document#clipboardInput](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-clipboardInput) event to override this behavior. For example, you can use it to:

* Handle pasted or dropped files. You can retrieve these from the `dataTransfer`.  
Handling file upload requires, however, a lot more than reading [dataTransfer.files](../../api/module%5Fengine%5Fview%5Fdatatransfer-ViewDataTransfer.html#member-files). For a complete code example, check the source code of plugins like [ImageUploadEditing](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/src/imageupload/imageuploadediting.ts).
* Change the type of data that the clipboard feature reads from the clipboard. For instance, you may want to use `application/rtf` if it is present in the `dataTransfer` (and ignore `text/html` in that case).  
```  
editor.editing.view.document.on( 'clipboardInput', ( evt, data ) => {  
    const dataTransfer = data.dataTransfer;  
    const rtfContent = dataTransfer.getData( 'application/rtf' );  
    // If no RTF was pasted, abort and let the clipboard feature handle the input.  
    if ( !rtfContent ) {  
        return;  
    }  
    // Convert an RTF raw string to a view document fragment.  
    const viewContent = convertRtfStringToView( rtfContent );  
    // Pass the view fragment to the default clipboard input handler  
    // to allow further processing of the content.  
    data.content = viewContent;  
} );  
```

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--processing-input-content">

#### Processing input content

The [ClipboardPipeline#inputTransformation](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-inputTransformation) event lets you process the content which is going to be inserted into the editor.

The default action is to fire a [ClipboardPipeline#contentInsertion](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-contentInsertion) event. This event will [insert](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) the content (`data.content`, represented by a [ViewDocumentFragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html)) to the editor if the data is not empty.

At this stage, features can process the pasted content. For example, you can implement a feature that wants to transform the pasted text into a link in the following way:

```
const writer = new ViewUpcastWriter( editor.editing.view.document );

editor.plugins.get( 'ClipboardPipeline' ).on( 'inputTransformation', ( evt, data ) => {
    if ( data.content.childCount == 1 && isUrlText( data.content.getChild( 0 ) ) ) {
        const linkUrl = data.content.getChild( 0 ).data;

        data.content = writer.createDocumentFragment( [
            writer.createElement(
                'a',
                { href: linkUrl },
                [ writer.createText( linkUrl ) ]
            )
        ] );
    }
} );

```

The default action (inserting the content into the editor) is performed by a low-priority listener, so it can be overridden by a normal one. With the `lowest` priority, you can also execute actions after the content has already been inserted.

```
editor.plugins.get( 'ClipboardPipeline' ).on( 'contentInsertion', ( evt, data ) => {
    console.log( 'Content was inserted.' );
}, { priority: 'lowest' } );

```

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--paste-as-plain-text-plugin-example">

#### Paste as plain text plugin example

You can use the knowledge from the earlier sections to create a complete plugin. A perfect example to follow is our [PastePlainText](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-clipboard/src/pasteplaintext.ts) which pastes plain text when Shift is pressed. If you are not familiar with creating plugins in CKEditor 5, start by reading the [Creating a simple plugin](#ckeditor5/latest/framework/tutorials/crash-course/editor.html) guide.

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--output-pipeline">

### Output pipeline

The output pipeline is the equivalent of the input pipeline but for the copy and cut operations. It allows to process the content that will be then put into the clipboard or to override the whole process.

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--output-pipeline-events-overview">

#### Output pipeline events overview

```
 ┌──────────────────────┐          ┌──────────────────────┐   Retrieves the selected
 │     view.Document    │          │     view.Document    │   model.DocumentFragment
 │         copy         │          │          cut         │   and fires the `outputTransformation`
 └───────────┬──────────┘          └───────────┬──────────┘   event.
             │                                 │
             └────────────────┌────────────────┘
                              │
                ┌─────────────V────────────┐   Processes model.DocumentFragment
                │     ClipboardPipeline    │   and converts it to
                │    outputTransformation  │   view.DocumentFragment.
                └──────────────────────────┘
                              │
                ┌─────────────V────────────┐   Processes view.DocumentFragment
                │       view.Document      │   to text/html and text/plain
                │      clipboardOutput     │   and stores results in data.dataTransfer.
                └──────────────────────────┘

```

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--1-on-link-moduleengineviewdocumentviewdocumenteventcopy-viewdocumentcopy-and-link-moduleengineviewdocumentviewdocumenteventcut-viewdocumentcut">

#### 1\. On [view.Document#copy](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-copy) and [view.Document#cut](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-cut)

The default action is to:

1. [Get the selected content](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-getSelectedContent) from the editor.
2. Prevent the default action of the native `copy` or `cut` event.
3. Fire [clipboard.ClipboardPipeline#outputTransformation](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-outputTransformation)\` with a selected content represented by a [model document fragment](../../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html).

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--2-on-link-moduleclipboardclipboardpipelineclipboardpipelineeventoutputtransformation-clipboardclipboardpipelineoutputtransformation">

#### 2\. On [clipboard.ClipboardPipeline#outputTransformation](../../api/module%5Fclipboard%5Fclipboardpipeline-ClipboardPipeline.html#event-outputTransformation)

The default action is to:

1. Processes `data.content` represented by a [model document fragment](../../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html).
2. Fire [view.Document#clipboardOutput](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-clipboardOutput) with a processed `data.content` converted to a [view document fragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html).

<a id="ckeditor5/latest/framework/deep-dive/clipboard.html--3-on-link-moduleengineviewdocumentviewdocumenteventclipboardoutput-viewdocumentclipboardoutput">

#### 3\. On [view.Document#clipboardOutput](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-clipboardOutput)

The default action is to put the content (`data.content`, represented by a [ViewDocumentFragment](../../api/module%5Fengine%5Fview%5Fdocumentfragment-ViewDocumentFragment.html)) to the clipboard as HTML. In the case of the cut operation, the selected content is also deleted from the editor.

This action is performed by a low-priority listener, so it can be overridden by a normal one.

At this stage other features can process the copied or cut content.

<a id="ckeditor5/latest/framework/deep-dive/conversion/attributes.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/attributes.html"</a>

## Attributes and inline formatting

In this guide, we will dive deeper into how inline formatting works in CKEditor 5 through the lens of model text attributes. To fully understand the concepts presented here, you should first study how [conversion](#ckeditor5/latest/framework/deep-dive/conversion/intro.html) works, particularly how attributes are transformed between the model and view layers.

<a id="ckeditor5/latest/framework/deep-dive/conversion/attributes.html--inline-and-block-content">

### Inline and block content

Generally speaking, there are two main types of content in the editor view and data output: inline and block.

The inline content means elements like `<strong>`, `<a>`, or `<span>`. Unlike `<p>`, `<blockquote>`, or `<div>`, the inline elements do not structure the data. Instead, they format some text in a specific (visual and semantical) way. These elements are characteristic of text. For instance, you could say that some part of the text is bold, is linked, and so on. This concept has its reflection in the model of the rich-text editor, where `<a>` or `<strong>` are not represented as elements. Instead, they are the attributes of the text.

For example – in the model, you might have a `<paragraph>` element with the “Foo bar” text, where “bar” has the `bold` attribute set to `true`. A pseudo-code of this _model_ data structure could look as follows:

```
<paragraph>
    "Foo "			// no attributes
    "bar"			// bold=true
</paragraph>

```

Note that there is no `<strong>` or any other additional element there; it is just some text with an attribute.

So, when does this text become wrapped with a `<strong>` element? This happens during the conversion to the view. It is also important to know what type of view element needs to be used. In the case of the elements that represent inline formatting, this should be an [attribute element](../../../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html).

<a id="ckeditor5/latest/framework/deep-dive/conversion/attributes.html--conversion-of-multiple-text-attributes">

### Conversion of multiple text attributes

A model text node may have multiple attributes (for example, be bolded and linked), and all of them are converted into their respective view elements by independent converters.

Keep in mind that in the model, attributes do not have any specific order. This is contrary to the editor view or HTML output, where inline elements are nested in one another. Fortunately, the nesting happens automatically during the conversion from the model to the view. This makes working in the model simpler, as features do not need to take care of breaking or rearranging elements in the model.

For instance, consider the following model structure:

```
<paragraph>
    <$text bold="true" linkHref="url">Foo </$text>
    <$text linkHref="url">bar</$text>
    <$text bold="true"> baz</$text>
</paragraph>

```

During the conversion, it will be converted to the following view structure:

```
<p>
    <a href="url"><strong>Foo </strong>bar</a><strong> baz</strong>
</p>

```

Note that the `<a>` element is converted in such a way that it always becomes the “topmost” element. This is intentional so that no element ever breaks a link, which would otherwise look as follows:

```
<p>
    <strong><a href="url">Foo </a></strong><a href="url">bar</a><strong> baz</strong>
</p>

```

There are two links with the same `href` attribute next to each other in the generated view (editor output), which is semantically wrong. To make sure that this never happens, the view element that represents a link must have a [priority](../../../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html#member-priority) defined. Most elements, like `<strong>`, do not care about it and stick to the default priority (`10`). The [Link feature](#ckeditor5/latest/features/link.html) ensures that all `<a>` view elements have the priority set to `5`, therefore they are kept outside other elements.

<a id="ckeditor5/latest/framework/deep-dive/conversion/attributes.html--merging-attribute-elements-during-conversion">

### Merging attribute elements during conversion

Priority is not only important for determining the nesting order of attribute elements. It also plays a crucial role in deciding whether adjacent attribute elements can be merged during the conversion process.

Inline elements in the view, such as `<strong>` or `<em>`, are typically simple formatting elements without additional attributes. However, some features require more complex styling. For example, the [Font family feature](#ckeditor5/latest/features/font.html) adds a `fontFamily` attribute to text in the model. During downcast, this model attribute is converted to a view `<span>` element with a corresponding `style` attribute, which then appears as a `<span style="font-family: ...">` in the HTML output.

What would, then, happen if several model attributes were set on the same part of the text? Take this model example where `fontSize` is used next to `fontFamily`:

```
<paragraph>
    <$text fontFamily="Tahoma" fontSize="big">foo</$text>
</paragraph>

```

CKEditor 5 features are implemented in a granular way, which means that the font size converter is completely independent from the font family converter. This means that the above example is converted as follows:

* `fontFamily="value"` converts to `<span style="font-family: value;">`,
* `fontSize="value"` converts to `<span class="text-value">`.

And, in theory, you could expect the following HTML as a result:

```
<p>
    <span style="font-family: Tahoma;">
        <span class="text-big">foo</span>
    </span>
</p>

```

But this is not the most optimal output you can get from the rich-text editor. A single `<span>` element would be better:

```
<p>
    <span style="font-family: Tahoma;" class="text-big">foo</span>
</p>

```

A single `<span>` makes more sense. And thanks to the merging mechanism built into the conversion process, this is the actual output of the conversion.

Why is this so? In the above scenario, two model attributes are converted to `<span>` elements. When the engine converts the first attribute (say, `fontFamily`), there is no `<span>` in the view yet. So the first `<span>` is added with the `style` attribute. But then, when the engine converts `fontSize`, the `<span>` is already in the view. The [downcast writer](../../../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html) recognizes it and checks whether these elements can be merged, following these three rules:

1. Both elements must have the same [name](../../../api/module%5Fengine%5Fview%5Felement-ViewElement.html#member-name).
2. Both elements must have the same [priority](../../../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html#member-priority).
3. Neither can have an [ID](../../../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html#member-id).

If you need to keep attributes separated (for example, to prevent merging between two visually identical but semantically distinct decorations), set a unique `id`. Otherwise, leave the `id` unset and let the engine merge.

<a id="ckeditor5/latest/framework/deep-dive/conversion/attributes.html--further-reading">

### Further reading

If you want to learn more about converting model attributes, we recommend checking out the following guides:

* [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--defining-converters) – A practical tutorial showing conversion in action.
* [Implementing an inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--defining-converters) – Learn how to implement inline widgets with custom conversion.

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/downcast.html"</a>

## Downcast conversion – model to view

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--introduction">

### Introduction

The process of converting the **model** to the **view** is called a **downcast**.

The downcast process happens every time a model node or attribute needs to be converted into a view node or attribute.

The editor engine runs the conversion process and uses converters registered by the plugins.

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--registering-a-converter">

### Registering a converter

To tell the engine how to convert a specific model element into a view element, you need to register a **downcast converter** by using the `editor.conversion.for( 'downcast' )` method, listing the elements that should be converted in the process:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'paragraph',
        view: 'p'
    } );

```

The above converter will handle the conversion of every `<paragraph>` model element into a `<p>` view element. You can see the input and output in the snippet below.

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--downcast-pipelines">

### Downcast pipelines

The CKEditor 5 engine uses two different views: the **data view** and the **editing view**.

The **data view** is used when generating the editor output. This process is controlled by the data pipeline.

The **editing view**, on the other hand, is what you see when you open the editor. This is controlled by the editing pipeline.

The simple code example presented before registers a converter for both of these pipelines at once. It means that a `<paragraph>` model element will be converted to a `<p>` view element in both the **data view** and the **editing view** all the same.

Sometimes you may want to alter the converter logic for a specific pipeline. For example, in the editing view you may want to add some additional class to the view element. This kind of operation requires setting separate converters for both views, unlike the previous example where one, general downcast was set up.

```
// dataDowncast for data pipeline
editor.conversion
    .for( 'dataDowncast' )
    .elementToElement( {
        model: 'paragraph',
        view: 'p'
    } );

// editingDowncast for editing pipeline
editor.conversion
    .for( 'editingDowncast' )
    .elementToElement( {
        model: 'paragraph',
        view: {
            name: 'p',
            classes: 'paragraph-in-editing-view'
        }
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--converting-text-attributes">

### Converting text attributes

As you should already know from the [chapter about the model](#ckeditor5/latest/framework/architecture/editing-engine.html--model), an **attribute** may be applied to a model text node.

Such text node attributes may be converted into view elements.

To do so, you can register a converter by using the [attributeToElement() conversion helper](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--attribute-to-element-conversion-helper):

```
editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'bold',
        view: 'strong'
    } );

```

The above converter will handle the conversion of every `bold` model text node attribute to a `<strong>` view element, as shown in the snippet below.

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--converting-element-to-element">

### Converting element to element

Similar to the previous example, you can convert a `<heading>` model element into an `<h1>` view element with the use of the [elementToElement() conversion helper](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--element-to-element-conversion-helper). A code to achieve it would look like this:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'heading',
        view: 'h1'
    } );

```

Which is equivalent to:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'heading',
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement(
                'h1'
            );
        }
    } );

```

You have previously learned that the `view` property can be a simple string or an object. The example above shows it is also possible to define a custom callback function to return the created element instead. The effect for this kind of conversion can be observed in the snippet below:

The `<heading>` element makes the most sense if you can set the heading level in the view.

In the previous chapter you have learned that you can apply attributes to text nodes. It is also possible to add attributes to elements, like in this example:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: {
            name: 'heading',
            attributes: [ 'level' ]
        },
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement(
                'h' + modelElement.getAttribute( 'level' )
            );
        }
    } );

```

From now on, every time a level attribute updates, the whole `<heading>` element will be converted to the `<h[level]>` element (for example `<h1>`, `<h2>`, etc).

You can check this in action by using the example below. Use the dropdown to change heading level in the model and see how view elements are updated by the converter:

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--converting-element-to-structure">

### Converting element to structure

Sometimes you may want to convert a **single model element** into a more complex view structure consisting of a **single view element with children**.

You can use the [elementToStructure() conversion helper](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--element-to-structure-conversion-helper) for this purpose:

```
editor.conversion
    .for( 'downcast' ).elementToStructure( {
        model: 'myElement',
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement( 'div', { class: 'wrapper' }, [
                writer.createContainerElement( 'div', { class: 'inner-wrapper' }, [
                    writer.createSlot()
                ] )
            ] );
        }
    } );

```

The above converter will convert all `<myElement>` model elements to `<div class="wrapper"><div class="inner-wrapper"><p>...</p></div></div>` structures, as shown below:

<a id="ckeditor5/latest/framework/deep-dive/conversion/downcast.html--further-reading">

### Further reading

If you want to learn more about downcast helpers mentioned in this guide, we have [rounded them up](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html) for you with complete descriptions and examples. We also recommend you to check out the [upcast conversion](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html) guide and learn how to convert raw data on the editor input into a live model state.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html"</a>

## Downcast helpers – model to view conversion

This article lists all editor helpers available in the [downcast conversion](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html).

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--element-to-element-conversion-helper">

### Element to element conversion helper

Converting a model element to a view element is the most common case of conversion. It is used to create view elements like `<p>` or `<h1>`, that we call “container elements.”

When using the `elementToElement()` helper, a **single model element** will be converted to a **single view element**. The children of this model element need to have their own converters defined and the engine will recursively convert them and insert into the created view element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--basic-element-to-element-conversion">

#### Basic element to element conversion

If you want to convert a model element to a simple view element without any additional attributes, simply provide their names through the converter, as shown in this example:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'paragraphSeparator',
        view: 'hr'
} );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--using-view-element-definition">

#### Using view element definition

Sometimes you may need to output a view element that has certain attributes, like a class name. To achieve this, you can provide an [element definition](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementDefinition.html) in the `view` property:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'fancyParagraph',
        view: {
            name: 'p',
            classes: 'fancy'
        }
    } );

```

Check out the [ViewElementObjectDefinition documentation](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementObjectDefinition.html) for more details.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--creating-a-view-element-using-a-callback">

#### Creating a view element using a callback

An alternative way to write a converter from the previous section using a callback would look as follows:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'fancyParagraph',
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement(
                'p', { class: 'fancy' }
            );
        }
    } );

```

Here, the second parameter of the view callback is the [DowncastConversionApi](../../../../api/module%5Fengine%5Fconversion%5Fdowncastdispatcher-DowncastConversionApi.html) object. It contains many properties and methods that can be useful when writing a more complex converters.

The callback should return a single container element. This element should not contain any children except UI elements. If you want to create a richer structure, use the `elementToStructure()` method.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--handling-model-elements-with-attributes">

#### Handling model elements with attributes

If the view element does not only depend on the model element itself but also on its attributes, you need to specify these attributes in the `model` property.

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: {
            name: 'heading',
            attributes: [ 'level' ]
        },
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement(
                'h' + modelElement.getAttribute( 'level' )
            );
        }
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--changing-converter-priority">

#### Changing converter priority

In case there are other converters with overlapping `model` patterns already present, you can prioritize your converter to override these. To do that, use the `converterPriority` property:

```
editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'userComment',
        view: 'div'
    } );

editor.conversion
    .for( 'downcast' )
    .elementToElement( {
        model: 'userComment',
        view: 'article',
        converterPriority: 'high'
    } );

```

In the example above, the first converter has no explicitly set priority hence it assumes default priority, which is `normal`. The second one overrides it by setting the priority to `high`. Using both of these converters at once will result in the `<userComment>` element being converted to an `<article>` element.

This solution may also be handy if you want your converter to act as a fallback when other converters for a given element are not present (for example, a plugin has not been loaded). It can be easily achieved by setting the `converterProperty` to `low`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--element-to-structure-conversion-helper">

### Element to structure conversion helper

Convert a single model element to multiple view elements (a structure of view elements).

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--handling-empty-model-elements">

#### Handling empty model elements

To convert a single model element `horizontalLine` to the following structure:

```
<div class="horizontal-line">
    <hr />
</div>

```

you can use a converter similar to this one:

```
editor.conversion
    .for( 'downcast' )
    .elementToStructure( {
        model: 'horizontalLine',
        view: ( modelElement, { writer } ) => {
            return writer.createContainerElement( 'div', { class: 'horizontal-line' }, [
                writer.createEmptyElement( 'hr' )
            ] );
        }
} );

```

Note that in this example we create two elements, which is not possible by using the previously mentioned `elementToElement()` helper.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--handling-model-elements-children">

#### Handling model element’s children

The example above uses an empty model element. If your model element may contain children, you need to specify where in the view these children should be placed. To do that, use the `writer.createSlot()` helper.

```
editor.conversion
    .for( 'downcast' )
    .elementToStructure( {
        model: 'wrappedParagraph',
        view: ( modelElement, conversionApi ) => {
            const { writer } = conversionApi;
            const paragraphViewElement = writer.createContainerElement( 'p', {}, [
                writer.createSlot()
            ] );

            return writer.createContainerElement( 'div', { class: 'wrapper' }, [
                paragraphViewElement
            ] );
        }
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--attribute-to-element-conversion-helper">

### Attribute to element conversion helper

The attribute to element conversion is used to create formatting view elements like `<b>` or `<span style="font-family: ...">` (that we call attribute elements). In this case, we do not convert a model element but a text node’s attribute. It is important to note that text formatting, such as bold or font size, should be represented in the model as text node attributes.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--basic-text-attribute-to-model-conversion">

#### Basic text attribute to model conversion

```
editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'bold',
        view: 'strong'
    } );

```

A model text node `"CKEditor&nbsp;5"` with a `bold` attribute will become a `<strong>"CKEditor&nbsp;5"</strong>` in the view.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--using-view-element-definition-2">

#### Using view element definition

You might want to output a view element that has more attributes, like a class name. To achieve that, you can provide an [element definition](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementDefinition.html) in the `view` property:

```
editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'invert',
        view: {
            name: 'span',
            classes: [ 'font-light', 'bg-dark' ]
        }
    } );

```

Check out the [ViewElementObjectDefinition documentation](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementObjectDefinition.html) for more details.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--creating-a-view-element-using-a-callback-2">

#### Creating a view element using a callback

You can also generate the view element by a callback. This method is useful when the view element depends on the value of the model attribute.

```
editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'bold',
        view: ( modelAttributeValue, conversionApi ) => {
            const { writer } = conversionApi;

            return writer.createAttributeElement( 'span', {
                style: 'font-weight:' + modelAttributeValue
            } );
        }
    } );

```

The second parameter of the view callback is the [DowncastConversionApi](../../../../api/module%5Fengine%5Fconversion%5Fdowncastdispatcher-DowncastConversionApi.html) object. It contains many properties and methods that can be useful when writing more complex converters.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--changing-converter-priority-2">

#### Changing converter priority

In case there are other converters already present, you can prioritize your converter to override the existing ones. To do that, use the `converterPriority` property:

```
editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'bold',
        view: 'strong'
    } );

editor.conversion
    .for( 'downcast' )
    .attributeToElement( {
        model: 'bold',
        view: 'b',
        converterPriority: 'high'
    } );

```

In the example above, the first converter has no explicitly set priority hence it assumes default priority, which is `normal`. The second one overrides it by setting the priority to `high`. Using both of these converters at once will result in the `bold` attribute being converted to a `<b>` element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--attribute-to-attribute-conversion-helper">

### Attribute to attribute conversion helper

The `attributeToAttribute()` helper allows registering a converter that handles a specific attribute and converts it to an attribute of a view element.

Usually, when registering converters for elements (for example, by using `elementToElement()` or `elementToStructure()`), you will want to handle their attributes while handling the element itself.

The `attributeToAttribute()` helper comes in handy when for some reason you cannot cover a specific attribute inside the `elementToElement()` helper. For instance, when you are extending someone else’s plugin.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--basic-attribute-to-attribute-conversion">

#### Basic attribute to attribute conversion

This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example, `<imageInline src='foo.jpg'></imageInline>` is converted to `<img src='foo.jpg'></img>`.

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: 'source',
        view: 'src'
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--converting-specific-model-element-and-attribute">

#### Converting specific model element and attribute

The converter in the example above will convert **all** the `source` model attributes in the document. You can limit its scope by providing the model element name. You achieve it with the following code:

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: {
            name: 'imageInline',
            key: 'source'
        },
        view: 'src'
    } );

```

This updated converter will only convert the `source` model attributes present on the `imageInline` model element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--creating-a-custom-view-element-from-a-selected-list-of-model-values">

#### Creating a custom view element from a selected list of model values

Once you provide the array in the `model.values` property, the `view` property is expected to be an object with keys matching these values. This is best explained using the example below:

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: {
            name: 'styled',
            values: [ 'dark', 'light' ]
        },
        view: {
            dark: {
                key: 'class',
                value: [ 'styled', 'styled-dark' ]
            },
            light: {
                key: 'class',
                value: [ 'styled', 'styled-light' ]
            }
        }
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--creating-a-view-attribute-with-a-custom-value-based-on-the-model-value">

#### Creating a view attribute with a custom value based on the model value

The value of the view attribute can be modified in the converter. Below is a simple mapper that sets the class attribute based on the model attribute value:

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: 'styled',
        view: modelAttributeValue => ( {
            key: 'class',
            value: 'styled-' + modelAttributeValue
        } )
    } );

```

It is worth noting that providing a style property in this manner requires the returned `value` to be an object:

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: 'lineHeight',
        view: modelAttributeValue => ( {
            key: 'style',
            value: {
                'line-height': modelAttributeValue,
                'border-bottom': '1px dotted #ba2'
            }
        } )
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--changing-converter-priority-3">

#### Changing converter priority

You can override the existing converters by specifying higher priority, like in the example below:

```
editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: 'source',
        view: 'href'
    } );

editor.conversion
    .for( 'downcast' )
    .attributeToAttribute( {
        model: 'source',
        view: 'src',
        converterPriority: 'high'
    } );

```

First converter has the default priority, `normal`. The second converter will be called earlier because of its higher priority, thus the `source` model attribute will get converted to `src` view attribute instead of `href`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--further-reading">

### Further reading

Check out the [dedicated guide](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html) with a full list of complementary [upcast conversion helpers](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html).

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/intro.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/helpers/intro.html"</a>

## Introduction to conversion helpers

The editor supports a vast amount of the most commonly used HTML elements via [existing editor features](#ckeditor5/latest/features/index.html) out-of-the-box.

If your aim is to easily enable common HTML features that are not explicitly supported by the dedicated CKEditor 5 features, use the [General HTML Support feature](#ckeditor5/latest/features/html/general-html-support.html).

There are, however, cases where you might want to provide a rich editing experience for a custom HTML markup. The conversion helpers are the way to achieve that. Read the following guides to learn how to use them.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/intro.html--helpers-by-category">

### Helpers by category

* **[Downcast helpers – model to view conversion](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html)**
* **[Upcast helpers – view to model conversion](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html)**

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html"</a>

## Upcast helpers – view to model conversion

This article lists all editor helpers available in the [upcast conversion](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html).

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--element-to-element-conversion-helper">

### Element to element conversion helper

Converting a view element to a model element is the most common case of conversion. It is used to handle view elements like `<p>` or `<h1>` which need to be converted to model elements.

With the use of the `elementToElement()` helper, a **single view element** will be converted to a **single model element**. The children of this view element need to have their own converters defined and the engine will recursively convert them and insert into the created model element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--basic-element-to-element-conversion">

#### Basic element to element conversion

The simplest case of an element to element conversion, where a view element becomes a model element can be achieved by simply providing their names within the converter:

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: 'p',
        model: 'paragraph'
    } );

```

The example above creates a model element `<paragraph>` from every `<p>` view element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--using-view-element-definition">

#### Using view element definition

You can limit the view elements that qualify for the conversion by specifying their attributes, like a class name. To achieve it, provide the desired element definition in the `view` property like in the example below:

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: {
            name: 'p',
            classes: 'fancy'
        },
        model: 'fancyParagraph'
    } );

```

Check out the [ViewElementObjectDefinition documentation](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementObjectDefinition.html) for more details.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--creating-a-model-element-using-a-callback">

#### Creating a model element using a callback

A model element resulting from the conversion can be created manually using a callback provided as a `model` property.

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: {
            name: 'p',
            classes: 'heading'
        },
        model: ( viewElement, { writer } ) => {
            return writer.createElement( 'heading' );
        }
    } );

```

In the example above, the model element is created only from the `<p class="heading">` view element. All other `<p>` elements without the `heading` class name will be filtered out and will not be converted.

The second parameter of the model callback is the [UpcastConversionApi](../../../../api/module%5Fengine%5Fconversion%5Fupcastdispatcher-UpcastConversionApi.html) object, that contains many properties and methods useful when writing more complex converters.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--handling-view-elements-with-attributes">

#### Handling view elements with attributes

If the model element depends not only on the view element itself but also on its attributes, you need to specify these attributes in the `view` property.

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: {
            name: 'p',
            attributes: [ 'data-level' ]
        },
        model: ( viewElement, { writer } ) => {
            return writer.createElement( 'heading', { level: viewElement.getAttribute( 'data-level' ) } );
        }
    } );

```

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--changing-converter-priority">

#### Changing converter priority

In case there are more converters with overlapping `view` patterns already present, you can prioritize your converter to override them. To do so, use the `converterPriority` property:

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: 'div',
        model: 'mainContent',
    } );

editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: 'div',
        model: 'sideContent',
        converterPriority: 'high'
    } );

```

In the above example, the first converter has the default priority, `normal` (no need to set it explicitly). The second one overrides it, having its priority set to `high`. Using both of these converters at once will result in the `<div>` view element being converted to `sideContent`.

Another practical application of this solution is to have your converter act as a fallback when other converters for a given element are not present (for example, a plugin has not been loaded). It can be easily achieved by setting the `converterProperty` to `low`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--element-to-attribute-conversion-helper">

### Element to attribute conversion helper

The element to attribute conversion is used to handle formatting view elements like `<b>` or `<span style="font-family: ...">` that need to be converted to text attributes. It is important to note that text formatting such as bold or font size should be represented in the model as text nodes attributes.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--basic-element-to-attribute-conversion">

#### Basic element to attribute conversion

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: 'strong',
        model: 'bold'
    } );

```

In the example above, the view `<strong>CKEditor&nbsp;5</strong>` will become the `CKEditor&nbsp;5` model text node with a `bold` attribute set to `true`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--converting-attribute-in-a-specific-view-element">

#### Converting attribute in a specific view element

You might want to only convert view elements with a specific class name or other attribute. To achieve it, you can provide [element definition](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementDefinition.html)) in the `view` property.

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: {
            name: 'span',
            classes: 'bold'
        },
        model: 'bold'
    } );

```

Check out the [ViewElementObjectDefinition documentation](../../../../api/module%5Fengine%5Fview%5Felementdefinition-ViewElementObjectDefinition.html) for more details.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--setting-a-predefined-value-to-model-attribute">

#### Setting a predefined value to model attribute

You can specify the value a model attribute will take. To achieve it, provide the name of the resulting model attribute as a `key` and its desired value as a `value` in `model` property object:

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: {
            name: 'span',
            classes: [ 'styled', 'styled-dark' ]
        },
        model: {
            key: 'styled',
            value: 'dark'
        }
    } );

```

The code above will convert `<span class="styled styled-dark">CKEditor5</span>` into a model text node `CKEditor5` with the `styled` attribute set to `dark`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--handling-attribute-values-via-a-callback">

#### Handling attribute values via a callback

In a situation when the value of an attribute needs additional processing (like mapping, filtering, etc.), you can define the `model.value` as a callback.

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: {
            name: 'span',
            styles: {
                'font-size': /[\s\S]+/
            }
        },
        model: {
            key: 'fontSize',
            value: ( viewElement, conversionApi ) => {
                const fontSize = viewElement.getStyle( 'font-size' );
                const value = fontSize.substr( 0, fontSize.length - 2 );

                if ( value <= 10 ) {
                    return 'small';
                } else if ( value > 12 ) {
                    return 'big';
                }

                return null;
            }
        }
    } );

```

In the above example we turn the numeric `font-size` inline style into either a `small` or `big` model attribute depending on the defined criteria.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--changing-converter-priority-2">

#### Changing converter priority

You can override the existing converters by specifying higher priority, like in the example below:

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: 'strong',
        model: 'bold'
    } );

editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: 'strong',
        model: 'important',
        converterPriority: 'high'
    } );

```

In this example, the first converter has the default priority, `normal`. The second one overrides it, having its priority set to `high`. Using both of these converters at once will result in the `<strong>` view element being converted to an `important` model attribute.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--attribute-to-attribute-conversion-helper">

### Attribute to attribute conversion helper

The `attributeToAttribute()` helper allows registering a converter that handles a specific attribute and converts it to an attribute of a model element.

Usually, when registering converters for elements (for example, by using `elementToElement()`), you will want to handle their attributes while handling the element itself.

The `attributeToAttribute()` helper comes in handy when, for some reason, you cannot cover a specific attribute inside `elementToElement()`. This may happen, for instance, when you are extending someone else’s plugin.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--basic-attribute-to-attribute-conversion">

#### Basic attribute to attribute conversion

This conversion results in adding an attribute to a model element, based on an attribute from a view element. For example, the `src` attribute in `<img src="foo.jpg">` will be converted to `source` in `<imageInline source="foo.jpg"></imageInline>`.

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: 'src',
        model: 'source'
    } );

```

Another way of constructing this converter is to provide a `view.key` property. You can see this executed in the example below:

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: {
            key: 'src'
        },
        model: 'source'
    } );

```

Both of these converters will produce the exact same results.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--converting-specific-view-elements-attribute">

#### Converting specific view element’s attribute

You can limit the element holding the attribute as well as the value of that attributes. Such a converter will be executed only in case of a full match.

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: {
            name: 'p',
            key: 'class',
            value: 'styled-dark'
        },
        model: {
            key: 'styled',
            value: 'dark'
        }
    } );

```

In the example above only the `styled-dark` class of a `<p>` element will be converted to a model attribute `styled` with a predefined value `dark`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--converting-view-attributes-that-match-a-more-complex-pattern">

#### Converting view attributes that match a more complex pattern

The pattern provided in a `view` property can be much more elaborate. Besides a string, you can also provide a regexp or a function that takes the attribute value and returns `true` or `false`.

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: {
            key: 'data-style',
            value: /\S+/
        },
        model: 'styled'
    } );

```

In the example above we are utilizing a regular expression to match only a selected `data-style` attribute that has no whitespace characters in its value. Only attributes that match this expression will have their value assigned to a `styled` model attribute.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--processing-attributes-via-callback">

#### Processing attributes via callback

If the value of an attribute needs additional processing (like mapping, filtering, etc.) you can define the `model.value` as a callback.

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: {
            key: 'class',
            value: /styled-[\S]+/
        },
        model: {
            key: 'styled'
            value: viewElement => {
                const regexp = /styled-([\S]+)/;
                const match = viewElement.getAttribute( 'class' ).match( regexp );

                return match[ 1 ];
            }
        }
    } );

```

The converter in the example above will extract the style name from each `class` attribute that starts with `styled-` and will assign it to a model attribute `styled`.

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--changing-converter-priority-3">

#### Changing converter priority

You can override the existing converters by specifying higher priority, like in the example below:

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: 'src',
        model: 'source'
    } );

editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: 'src',
        model: 'sourceAddress',
        converterPriority: 'high'
    } );

```

First converter has the default `normal` priority. The second converter will be called earlier because of its higher priority, thus the `src` view attribute will get converted to a `sourceAddress` model attribute (instead of `source`).

<a id="ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--further-reading">

### Further reading

Check out a [dedicated guide](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html) with a full list of complementary [downcast conversion helpers](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html).

<a id="ckeditor5/latest/framework/deep-dive/conversion/intro.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/intro.html"</a>

## Introduction to conversion

<a id="ckeditor5/latest/framework/deep-dive/conversion/intro.html--what-is-the-conversion">

### What is the conversion?

The [editing engine](#ckeditor5/latest/framework/architecture/editing-engine.html) of CKEditor 5 works on two separate layers – [model](#ckeditor5/latest/framework/architecture/editing-engine.html--model) and [view](#ckeditor5/latest/framework/architecture/editing-engine.html--view). The process of transforming one into the other is called conversion.

<a id="ckeditor5/latest/framework/deep-dive/conversion/intro.html--upcast-conversion">

#### Upcast conversion

When you load data into the editor, the view is created out of the markup. Then, with the help of the upcast converters, the model is created. Once that is done, the model becomes the editor state. The whole process is called upcast conversion.

<a id="ckeditor5/latest/framework/deep-dive/conversion/intro.html--downcast-conversion">

#### Downcast conversion

All changes, such as typing or pasting from the clipboard, are applied directly to the model. To update the editing view, e.i. the layer being displayed to the user, the engine transforms these changes in the model to the view. The same process is executed when data needs to be generated (for example, when you copy editor content or use `editor.getData()`). These processes are called editing and downcast conversions.

You can think about upcast and downcast as processes working in opposite directions, ones that are symmetrical to each other.

<a id="ckeditor5/latest/framework/deep-dive/conversion/intro.html--further-reading">

### Further reading

In the following guides, you will learn how to create the right converter for each case when creating your CKEditor 5 plugin.

* **[Model to view (downcast)](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html)**  
The model has to be transformed into the view. Learn how to achieve that by creating downcast converters.
* **[View to model (upcast)](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html)**  
Raw data coming into the editor has to be transformed into the model. Learn how to achieve that by creating upcast converters.
* **[Conversion helpers](#ckeditor5/latest/framework/deep-dive/conversion/helpers/intro.html)**  
There are plenty of ways to transform data between model and view. To help you do this as efficiently as possible, we provided many functions that speed up this process. This chapter will help you choose the right helper for the job.
* **[Attributes and inline formatting](#ckeditor5/latest/framework/deep-dive/conversion/attributes.html)**  
Understand how text attributes map to inline elements, how nesting and merging work, and what to watch for when integrating formatting features.

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html">source file: "ckeditor5/latest/framework/deep-dive/conversion/upcast.html"</a>

## Upcast conversion – view to model

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--introduction">

### Introduction

The process of converting the **view** to the **model** is called an **upcast**.

The upcast process conversion happens every time any data is being loaded into the editor.

Incoming data becomes the view which is then converted into the model via registered converters.

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--registering-a-converter">

### Registering a converter

To instruct the engine how to convert a specific view element into a model element, you need to register an **upcast converter** by using the `editor.conversion.for( 'upcast' )` method:

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: 'p',
        model: 'paragraph'
    } );

```

The above converter will handle the conversion of every `<p>` view element to a `<paragraph>` model element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--upcast-pipeline">

### Upcast pipeline

Contrary to the downcast where you deal with both the data and editing pipelines, the upcast process only happens in the data pipeline and is called **data upcast**.

The editing view may be only changed via changing the model first, hence editing pipeline needs only the downcast process.

The previous code example registers a converter for both pipelines at once. It means that a `<paragraph>` model element will be converted to a `<p>` view element in both the **data view** and the **editing view**.

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--converting-to-text-attribute">

### Converting to text attribute

View elements representing inline text formatting (such as `<strong>` or `<i>`) need to be converted to an attribute on a model text node.

To register such a converter, use the [elementToAttribute() method](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--element-to-attribute-conversion-helper):

```
editor.conversion
    .for( 'upcast' )
    .elementToAttribute( {
        view: 'strong',
        model: 'bold'
    } );

```

A text wrapped with the `<strong>` tag will be converted to a model text node with a `bold` attribute applied to it, as shown:

If you need to “copy” an attribute from a view element to a model element, use the [attributeToAttribute() method](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--attribute-to-attribute-conversion-helper).

The model element must have its own converter registered, otherwise there is nothing the attribute can be copied to.

```
editor.conversion
    .for( 'upcast' )
    .attributeToAttribute( {
        view: 'src',
        model: 'source'
    } );

```

Assuming that some other feature registered the `<img>` to `<image>` model element upcast converter in the editor, you can extend this feature to allow the `src` attribute. This attribute will be converted into a `source` attribute on a model element, the way it is shown in the following snippet:

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--converting-to-element">

### Converting to element

Converting a view element to a corresponding model element can be achieved by registering the converter using the [elementToElement() method](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--element-to-element-conversion-helper):

```
editor.conversion
    .for( 'upcast' )
    .elementToElement( {
        view: {
            name: 'div',
            classes: [ 'example' ]
        },
        model: 'example'
    } );

```

This converter will handle the conversion of every `<div class="example">` view element into an `<example>` model element.

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--converting-structures">

### Converting structures

As you have learnt in the [previous chapter](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html), a single model element can be downcast into a structure of multiple view elements.

The opposite process will have to detect that structure (for example, the main element) and convert it into a simple model element.

There is no `structureToElement()` helper available for the upcast conversion. To register an upcast converter for the entire structure and create a single model element, you must use the event-based API. The following example shows how to achieve it:

```
editor.conversion.for( 'upcast' ).add( dispatcher => {
    // Look for every view <div> element.
    dispatcher.on( 'element:div', ( evt, data, conversionApi ) => {
        // Get all the necessary items from the conversion API object.
        const {
            consumable,
            writer,
            safeInsert,
            convertChildren,
            updateConversionResult
        } = conversionApi;

        // Get view item from data object.
        const { viewItem } = data;

        // Define elements consumables.
        const wrapper = { name: true, classes: 'wrapper' };
        const innerWrapper = { name: true, classes: 'inner-wrapper' };

        // Tests if the view element can be consumed.
        if ( !consumable.test( viewItem, wrapper ) ) {
            return;
        }

        // Check if there is only one child.
        if ( viewItem.childCount !== 1 ) {
            return;
        }

        // Get the first child element.
        const firstChildItem = viewItem.getChild( 0 );

        // Check if the first element is a <div>.
        if ( !firstChildItem.is( 'element', 'div' ) ) {
            return;
        }

        // Tests if the first child element can be consumed.
        if ( !consumable.test( firstChildItem, innerWrapper ) ) {
            return;
        }

        // Create model element.
        const modelElement = writer.createElement( 'myElement' );

        // Insert element on a current cursor location.
        if ( !safeInsert( modelElement, data.modelCursor ) ) {
            return;
        }

        // Consume the main outer wrapper element.
        consumable.consume( viewItem, wrapper );
        // Consume the inner wrapper element.
        consumable.consume( firstChildItem, innerWrapper );

        // Handle children conversion inside inner wrapper element.
        convertChildren( firstChildItem, modelElement );

        // Necessary function call to help setting model range and cursor
        // for some specific cases when elements being split.
        updateConversionResult( modelElement, data );
    } );
} );

```

This converter will detect all `<div class="wrapper"><div class="inner-wrapper"><p>...</p></div></div>` structures (by scanning for the outer `<div>`s and turning those into a single `<myElement>` model element). The effect should return as follows:

<a id="ckeditor5/latest/framework/deep-dive/conversion/upcast.html--further-reading">

### Further reading

If you want to learn more about upcast helpers mentioned in this guide, we have [rounded them up](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html) for you with complete descriptions and examples. We also recommend you to check out the [downcast conversion](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html) guide and learn how to convert the editor model state into data output and editing view.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html">source file: "ckeditor5/latest/framework/deep-dive/event-system.html"</a>

## Event system

[Emitters](../../api/module%5Futils%5Femittermixin-Emitter.html) are objects that can fire events. They also provide means to listen to other emitters’ events.

Emitters are heavily used throughout the entire editor architecture. They are the building blocks for mechanisms such as the [observables](#ckeditor5/latest/framework/deep-dive/observables.html), [engine’s view observers](#ckeditor5/latest/framework/architecture/editing-engine.html--observers), and [conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion).

Any class can become an event emitter. All you need to do is mix the [Emitter](../../api/module%5Futils%5Femittermixin-Emitter.html) into it:

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--listening-to-events">

### Listening to events

Adding a callback to an event is simple. You can listen directly on the emitter object and use an anonymous function:

```
emitter.on( 'eventName', ( eventInfo, ...args ) => { /* ... */ } );

```

However, a function object is needed if you want to be able to remove the event listener:

```
emitter.off( 'eventName', handler );

```

There is also another way to add an event listener – by using [listenTo()](../../api/module%5Futils%5Femittermixin-Emitter.html#function-listenTo:BASE%5FEMITTER). This way one emitter can listen to events on another emitter:

```
foo.listenTo( bar, 'eventName', ( eventInfo, ...args ) => { /* ... */ } );

```

Now you can easily detach the `foo` from `bar` simply by [stopListening()](../../api/module%5Futils%5Femittermixin-Emitter.html#function-stopListening:BASE%5FSTOP).

```
// Stop listening to a specific handler.
foo.stopListening( bar, 'eventName', handler );

// Stop listening to a specific event.
foo.stopListening( bar, 'eventName' );

// Stop listening to all events fired by a specific emitter.
foo.stopListening( bar );

// Stop listening to all events fired by all bound emitters.
foo.stopListening();

```

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--listener-priorities">

#### Listener priorities

By default, all listeners are bound on the [normal](../../api/module%5Futils%5Fpriorities-PriorityString.html) priority, but you can specify the priority when registering a listener:

```
this.on( 'eventName', () => { /* ... */ }, { priority: 'high' } );
this.listenTo( emitter, 'eventName', () => { /* ... */ }, { priority: 'high' } );

```

There are 5 named priorities:

* `highest`
* `high`
* `normal`
* `low`
* `lowest`

Listeners are triggered in the order of these priorities (first `highest`, then `high`, etc.). For multiple listeners attached on the same priority, they are fired in the order of the registration.

**Note**: If any listener [stops](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-stop) the event, no other listeners including those on lower priorities will be called.

It is possible to use relative priorities [priorities.get( 'high' ) + 10](../../api/module%5Futils%5Fpriorities-PrioritiesType.html#function-get) but this is strongly discouraged.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--stopping-events-and-returned-value">

#### Stopping events and returned value

The first argument passed to an event handler is always an instance of the [EventInfo](../../api/module%5Futils%5Feventinfo-EventInfo.html). There you can check the event [name](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-name), the [source emitter](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-source) of the event, and you can [stop()](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-stop) the event from further processing.

```
emitter.on( 'eventName', ( eventInfo, data ) => {
    console.log( 'foo' );
    eventInfo.stop();
} );

emitter.on( 'eventName', ( eventInfo, data ) => {
    console.log( 'bar' ); // This won't be called.
} );

emitter.fire( 'eventName' ); // Logs "foo" only.

```

Listeners can set the [return](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-return) value. This value will be returned by [fire()](../../api/module%5Futils%5Femittermixin-Emitter.html#function-fire) after all callbacks are processed.

```
emitter.on( 'eventName', ( eventInfo, data ) => {
    eventInfo.return = 123;
} );

emitter.fire( 'eventName' ); // -> 123

```

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--listening-on-namespaced-events">

#### Listening on namespaced events

The event system supports namespaced events to give you the possibility to build a structure of callbacks. You can achieve namespacing by using `:` in the event name:

```
this.fire( 'foo:bar:baz', data );

```

Then the listeners can be bound to a specific event or the whole namespace:

```
this.on( 'foo', () => { /* ... */ } );
this.on( 'foo:bar', () => { /* ... */ } );
this.on( 'foo:bar:baz', () => { /* ... */ } );

```

This way you can have more general events, listening to a broader event (`'foo'` in this case), or more detailed callbacks listening to specified events (`'foo:bar'` or `'foo:bar:baz'`).

This mechanism is used for instance in the conversion, where thanks to events named `'insert:<elementName>'` you can listen to the insertion of a specific element (like `'insert:p'`) or all elements insertion (`'insert'`).

**Note**: Listeners registered on the same priority will be fired in the order of the registration (no matter if listening to a whole namespace or to a specific event).

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--firing-events">

### Firing events

Once you mix the [Emitter](../../api/module%5Futils%5Femittermixin-Emitter.html) into your class, you can fire events the following way:

```
this.fire( 'eventName', argA, argB, /* ... */ );

```

All passed arguments will be available in all listeners that are added to the event.

**Note**: Most base classes (like [Command](../../api/module%5Fcore%5Fcommand-Command.html) or [Plugin](../../api/module%5Fcore%5Fplugin-Plugin.html)) are [emitters](../../api/module%5Futils%5Femittermixin-Emitter.html) already and fire their own events.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--stopped-events">

#### Stopped events

It is sometimes useful to know if an event was stopped by any of the listeners. There is an alternative way of firing an event just for that:

Note that [EventInfo](../../api/module%5Futils%5Feventinfo-EventInfo.html) expects the source object in the first parameter as the origin of the event.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--event-return-value">

#### Event return value

If any handler set the [eventInfo.return](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-return) field, this value will be returned by [fire()](../../api/module%5Futils%5Femittermixin-Emitter.html#function-fire) after all callbacks are processed.

```
emitter.on( 'eventName', ( eventInfo, ...args ) => {
    eventInfo.return = 123;
} );

const result = emitter.fire( 'eventName', argA, argB, /* ... */ );

console.log( result ); // -> 123

```

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--delegating-events">

### Delegating events

The [Emitter](../../api/module%5Futils%5Femittermixin-Emitter.html) interface also provides the [event delegation](../../api/module%5Futils%5Femittermixin-Emitter.html#function-delegate) mechanism, so that selected events are fired by another [Emitter](../../api/module%5Futils%5Femittermixin-Emitter.html).

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--setting-events-delegation">

#### Setting events delegation

Delegate specific events to another emitter:

```
emitterA.delegate( 'foo' ).to( emitterB );
emitterA.delegate( 'foo', 'bar' ).to( emitterC );

```

You can delegate events with a different name:

```
emitterA.delegate( 'foo' ).to( emitterB, 'bar' );
emitterA.delegate( 'foo' ).to( emitterB, name => `delegated:${ name }` );

```

It is also possible to delegate all the events:

```
emitterA.delegate( '*' ).to( emitterB );

```

**Note**: Delegated events are fired from the target emitter no matter if they were stopped in any handler on the source emitter.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--stopping-delegation">

#### Stopping delegation

You can stop delegation by calling the [stopDelegating()](../../api/module%5Futils%5Femittermixin-Emitter.html#function-stopDelegating) method. It can be used at different levels:

```
// Stop delegating all events.
emitterA.stopDelegating();

// Stop delegating a specific event to all emitters.
emitterA.stopDelegating( 'foo' );

// Stop delegating a specific event to a specific emitter.
emitterA.stopDelegating( 'foo', emitterB );

```

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--delegated-event-info">

#### Delegated event info

The delegated events provide the [path](../../api/module%5Futils%5Feventinfo-EventInfo.html#member-path) of emitters that this event met along the delegation path.

```
emitterA.delegate( 'foo' ).to( emitterB, 'bar' );
emitterB.delegate( 'bar' ).to( emitterC, 'baz' );

emitterA.on( 'foo', eventInfo => console.log( 'event', eventInfo.name, 'emitted by A; source:', eventInfo.source, 'path:', eventInfo.path ) );
emitterB.on( 'bar', eventInfo => console.log( 'event', eventInfo.name, 'emitted by B; source:', eventInfo.source, 'path:', eventInfo.path ) );
emitterC.on( 'baz', eventInfo => console.log( 'event', eventInfo.name, 'emitted by C; source:', eventInfo.source, 'path:', eventInfo.path ) );

emitterA.fire( 'foo' );

// Outputs:
//   event "foo" emitted by A; source: emitterA; path: [ emitterA ]
//   event "bar" emitted by B; source: emitterA; path: [ emitterA, emitterB ]
//   event "baz" emitted by C; source: emitterA; path: [ emitterA, emitterB, emitterC ]

```

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--view-events-bubbling">

### View events bubbling

The [view.Document](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html) is not only an [Observable](../../api/module%5Futils%5Fobservablemixin-Observable.html) and an [emitter](../../api/module%5Futils%5Femittermixin-Emitter.html) but it also implements the special [BubblingEmitter](../../api/module%5Fengine%5Fview%5Fobserver%5Fbubblingemittermixin-BubblingEmitter.html) interface (implemented by [BubblingEmitterMixin](../../api/module%5Fengine%5Fview%5Fobserver%5Fbubblingemittermixin.html#function-BubblingEmitterMixin)). It provides a mechanism for bubbling events over the virtual DOM tree.

It is different from the bubbling that you know from the DOM tree event bubbling. You do not register listeners on specific instances of the elements in the view document tree. Instead, you can register handlers for specific contexts. A context is either a name of an element, or one of the virtual contexts (`'$capture'`, `'$text'`, `'$root'`, `'$document'`), or a callback to match desired nodes.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--listening-to-bubbling-events">

#### Listening to bubbling events

Listeners registered in the context of the view element names:

```
this.listenTo( view.document, 'enter', ( evt, data ) => {
    // Listener's code.
    // ...
}, { context: 'blockquote' } );

this.listenTo( view.document, 'enter', ( evt, data ) => {
    // Listener's code.
    // ...
}, { context: 'li' } );

```

Listeners registered in the virtual contexts:

```
this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
    // Listener's code.
    // ...
}, { context: '$text', priority: 'high' } );

this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
    // Listener's code.
    // ...
}, { context: '$root' } );

this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
    // Listener's code.
    // ...
}, { context: '$capture' } );

```

Listeners registered in the context of a custom callback function:

**Note**: Without specifying the `context`, events are bound to the `'$document'` context.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--bubbling-events-flow">

#### Bubbling events flow

Bubbling always starts from the virtual `'$capture'` context. All listeners attached to this context are triggered first (and in the order of their priorities).

Then, the real bubbling starts from the selection position (either its anchor or focus – depending on what is deeper).

If text nodes are allowed at the selection position, then the first context is `'$text'`. Then the event bubbles through all elements up to the `'$root'` and finally `'$document'`.

In all contexts listeners can be registered at desired priorities. If a listener stops an event, this event is not fired for the remaining contexts.

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--examples">

#### Examples

Assuming the given content and selection:

```
<blockquote>
    <p>
        Foo[]bar
    </p>
</blockquote>

```

Events will be fired for the following contexts:

1. `'$capture'`
2. `'$text'`
3. `'p'`
4. `'blockquote'`
5. `'$root'`
6. `'$document'`

Assuming the given content and selection (on a widget):

```
<blockquote>
    <p>
        Foo
        [<img />]	// enhanced with toWidget()
        bar
    </p>
</blockquote>

```

Events will be fired for the following contexts:

1. `'$capture'`
2. `'img'`
3. _widget_ (assuming a custom matcher was used)
4. `'p'`
5. `'blockquote'`
6. `'$root'`
7. `'$document'`

An even more complex example:

```
<blockquote>
    <figure class="table">	// enhanced with toWidget()
        <table>
            <tr>
                <td>
                    <p>
                        foo[]bar
                    </p>
                </td>
            </tr>
        </table>
    </figure>
</blockquote>

```

Events that will be fired:

1. `'$capture'`
2. `'$text'`
3. `'p'`
4. `'td'`
5. `'tr'`
6. `'table'`
7. `'figure'`
8. _widget_ (assuming a custom matcher was used)
9. `'blockquote'`
10. `'$root'`
11. `'$document'`

<a id="ckeditor5/latest/framework/deep-dive/event-system.html--bubblingeventinfo">

#### `BubblingEventInfo`

In some events the first parameter is not the standard `EventInfo`, but [BubblingEventInfo](../../api/module%5Fengine%5Fview%5Fobserver%5Fbubblingeventinfo-BubblingEventInfo.html). This is an extension that provides the current [eventPhase](../../api/module%5Fengine%5Fview%5Fobserver%5Fbubblingeventinfo-BubblingEventInfo.html#member-eventPhase) and [currentTarget](../../api/module%5Fengine%5Fview%5Fobserver%5Fbubblingeventinfo-BubblingEventInfo.html#member-currentTarget).

Currently, this information is available for the following events:

* [enter](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-enter),
* [delete](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-delete),
* [arrowKey](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-arrowKey).

Hence the events from the above example would be extended with the following `eventPhase` data:

1. `'$capture'` \- _capturing_
2. `'$text'` \- _at target_
3. `'p'` \- _bubbling_
4. `'td'` \- _bubbling_
5. `'tr'` \- _bubbling_
6. `'table'` \- _bubbling_
7. `'figure'` \- _bubbling_
8. _widget_ \- _bubbling_
9. `'blockquote'` \- _bubbling_
10. `'$root'` \- _bubbling_
11. `'$document'` \- _bubbling_

And for the example with the widget selected:

```
<blockquote>
    <p>
        Foo
        [<img />]	 // Enhanced with toWidget().
        bar
    </p>
</blockquote>

```

Events that will be fired:

1. `'$capture'` \- _capturing_
2. `'img'` \- _at target_
3. _widget_ \- _at target_ (assuming a custom matcher was used)
4. `'p'` \- _bubbling_
5. `'blockquote'` \- _bubbling_
6. `'$root'` \- _bubbling_
7. `'$document'` \- _bubbling_

<a id="ckeditor5/latest/framework/deep-dive/observables.html">source file: "ckeditor5/latest/framework/deep-dive/observables.html"</a>

## Observables

[Observables](../../api/module%5Futils%5Fobservablemixin-Observable.html) are objects which have properties that can be observed. That means when the value of such property changes, an event is fired by the observable and the change can be reflected in other pieces of the code that listen to that event.

Observables are common building blocks of the [CKEditor 5 Framework](#ckeditor5/latest/framework/index.html). They are particularly popular in the UI, the [View](../../api/module%5Fui%5Fview-View.html) class and its subclasses benefiting from the observable interface the most: it is the [templates bound to the observables](#ckeditor5/latest/framework/architecture/ui-library.html--interaction) what makes the user interface dynamic and interactive. Some of the basic classes like [Editor](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) or [Command](../../api/module%5Fcore%5Fcommand-Command.html) are observables too.

Any class can become observable; all you need to do is mix the [Observable](../../api/module%5Futils%5Fobservablemixin-Observable.html) into it:

Observables are useful when it comes to managing the state of the application, which can be dynamic and, more often than not, centralized and shared between components of the application. One observable can also propagate its state (or its part) to another using [property bindings](#ckeditor5/latest/framework/deep-dive/observables.html--property-bindings).

Observables can also [decorate their methods](#ckeditor5/latest/framework/deep-dive/observables.html--decorating-object-methods) which makes it possible to control their execution using event listeners, giving external code some control over their behavior.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--making-properties-observable">

### Making properties observable

Having mixed the [Observable](../../api/module%5Futils%5Fobservablemixin-Observable.html) into your class, you can define observable properties. To do that, use the [set() method](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-set:KEY%5FVALUE).

Let’s create a simple UI view (component) named `Button` with a couple of properties and see what they look like:

```
class Button extends View {
    constructor() {
        super();

        // This property is not observable.
        // Not all properties must be observable, it's always up to you!
        this.type = 'button';

        const bind = this.bindTemplate;

        // this.label is observable but undefined.
        this.set( 'label' );

        // this.isOn is observable and false.
        this.set( 'isOn', false );

        // this.isEnabled is observable and true.
        this.set( 'isEnabled', true );

        // More observable's properties.
        // ...
    }
}

```

Note that because `Button` extends the [View](../../api/module%5Fui%5Fview-View.html) class (which is already observable), you do not need to mix the `ObservableMixin`.

Finally, let’s create a new view and see how it communicates with the world.

Each time the `label` property changes, the view fires the `change:label` event containing information about its state in the past and the new value. The `change:isEnabled` and `change:isOn` events will be fired for changes of `isEnabled` and `isOn`, respectively.

```
const view = new Button();

view.on( 'change:label', ( evt, propertyName, newValue, oldValue ) => {
    console.log(
        `#${ propertyName } has changed from "${ oldValue }" to "${ newValue }"`
    );
} )

view.label = 'Hello world!'; // -> #label has changed from "undefined" to "Hello world!"
view.label = 'Bold'; // -> #label has changed from "Hello world!" to "Bold"

view.type = 'submit'; // Changing a regular property fires no event.

```

The events fired by the view are used to update the DOM and make the component dynamic. Let’s give our view some template and bind it to the observable properties we created.

```
class Button extends View {
    constructor() {
        super();

        // Previously defined properties.
        // ...

        // This template will have the following symbolic representation in DOM:
        //
        // 	<button class="[ck-disabled] ck-[on|off]" type="button">
        // 		{{ this.label }}
        // 	</button>
        //
        this.setTemplate( {
            tag: 'button',
            attributes: {
                class: [
                    // The 'ck-on' and 'ck-off' classes toggle according to the #isOn property.
                    bind.to( 'isOn', value => value ? 'ck-on' : 'ck-off' ),

                    // The 'ck-enabled' class appears when the #isEnabled property is false.
                    bind.if( 'isEnabled', 'ck-disabled', value => !value )
                ],
                type: this.type
            },
            children: [
                {
                    // The text of the button is bound to the #label property.
                    text: bind.to( 'label' )
                }
            ]
        } );
    }
}

```

Because `label`, `isOn`, and `isEnabled` are observables, any change will be immediately reflected in DOM:

```
const button = new Button();

// Render the button to create its #element.
button.render();

button.label = 'Bold';     // <button class="ck-off" type="button">Bold</button>
button.isOn = true;        // <button class="ck-on" type="button">Bold</button>
button.label = 'B';        // <button class="ck-on" type="button">B</button>
button.isOff = false;      // <button class="ck-off" type="button">B</button>
button.isEnabled = false;  // <button class="ck-off ck-disabled" type="button">B</button>

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--property-bindings">

### Property bindings

One observable can also propagate its state (or part of it) to another observable to simplify the code, for example, to avoid many `change:property` event listeners. To start binding object properties, make sure both objects (classes) mix the [Observable](../../api/module%5Futils%5Fobservablemixin-Observable.html), then use the [bind()](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-bind:SINGLE%5FBIND) method to create the binding.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--simple-bindings">

#### Simple bindings

Use the bold button instance from the previous section and bind it to the bold command. That will let the button use certain command properties and automate the user interface in just a couple of lines.

The bold command is an actual command of the editor (registered by the [BoldEditing](../../api/module%5Fbasic-styles%5Fbold%5Fboldediting-BoldEditing.html)) and offers two observable properties: `value` and `isEnabled`. To get the command, use `editor.commands.get( 'bold' )`.

Note that both `Button` and [Command](../../api/module%5Fcore%5Fcommand-Command.html) classes are [observable](../../api/module%5Futils%5Fobservablemixin-Observable.html), which is why you can bind their properties.

```
const button = new Button();
const command = editor.commands.get( 'bold' );

```

Any “decent” button must update its look when the command becomes disabled. A simple property binding doing that could look as follows:

```
button.bind( 'isEnabled' ).to( command );

```

After that:

* `button.isEnabled` **instantly equals** `command.isEnabled`,
* whenever `command.isEnabled` changes, `button.isEnabled` will immediately reflect its value,
* because the template of the button has its class bound to `button.isEnabled`, the DOM element of the button will also be updated.

Note that `command.isEnabled` **must** be defined using the `set()` method for the binding to be dynamic. In this case we are lucky because [isEnabled](../../api/module%5Fcore%5Fcommand-Command.html#member-isEnabled) is a standard observable property of every command in the editor. But keep in mind that when you create your own observable class, using `set()` method is the only way to define observable properties.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--renaming-properties">

##### Renaming properties

Now let’s dive into the `bind( /* ... */ ).to( /* ... */ )` syntax for a minute. As a matter of fact, the last example corresponds to the following code:

```
const button = new Button();
const command = editor.commands.get( 'bold' );

button.bind( 'isEnabled' ).to( command, 'isEnabled' );

```

You probably noticed the `to( /* ... */ )` interface which helps specify the name of the property (or just “rename” the property in the binding).

Both `Button` and `Command` class share the same `isEnabled` property, which allowed us to shorten the code. But if we decided to bind the `Button#isOn` to the `Command#value`, the code would be as follows:

```
button.bind( 'isOn' ).to( command, 'value' );

```

The property has been “renamed” in the binding and from now on, whenever `command.value` changes, the value of `button.isOn` will reflect it.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--processing-a-property-value">

##### Processing a property value

Another use case is processing the bound property value, for instance, when a button should be disabled only if certain conditions are met. Passing a callback as the third parameter allows implementing a custom logic.

In the example below, the `isEnabled` property will be set to `true` only when `command.value` equals `'heading1'`.

```
const command = editor.commands.get( 'heading' );
button.bind( 'isOn' ).to( command, 'value', value => value === 'heading1' );

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--binding-multiple-properties">

#### Binding multiple properties

It is possible to bind more that one property at a time to simplify the code:

```
const button = new Button();
const command = editor.commands.get( 'bold' );

button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

```

which is the same as:

```
button.bind( 'isOn' ).to( command, 'value' );
button.bind( 'isEnabled' ).to( command, 'isEnabled' );

```

In the above binding, the value of `button.isEnabled` will reflect `command.isEnabled` and the value of `button.isOn` will reflect `command.value`.

Note that the `value` property of the command has also been “renamed” in the binding like in the [previous example](#ckeditor5/latest/framework/deep-dive/observables.html--renaming-properties).

<a id="ckeditor5/latest/framework/deep-dive/observables.html--binding-with-multiple-observables">

#### Binding with multiple observables

The binding can include more than one observable, combining multiple properties in a custom callback function. Let’s create a button that gets enabled only when the `command` is enabled and the [editing document](../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html) (also an `Observable`) is focused:

```
const button = new Button();
const command = editor.commands.get( 'bold' );
const editingDocument = editor.editing.view.document;

button.bind( 'isEnabled' ).to( command, 'isEnabled', editingDocument, 'isFocused',
    ( isCommandEnabled, isDocumentFocused ) => isCommandEnabled && isDocumentFocused );

```

The binding makes the value of `button.isEnabled` depend both on `command.isEnabled` and `editingDocument.isFocused` as specified by the function: both must be `true` for the button to become enabled.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--binding-with-an-array-of-observables">

#### Binding with an array of observables

It is possible to bind the same property to an array of observables. Let’s bind our button to multiple commands so that each and every one must be enabled for the button to become enabled:

```
const button = new Button();
const commands =  [ commandA, commandB, commandC ];

button.bind( 'isEnabled' ).toMany( commands, 'isEnabled', ( isAEnabled, isBEnabled, isCEnabled ) => {
    return isAEnabled && isBEnabled && isCEnabled;
} );

```

The binding can be simplified using the spread operator (`...`) and the `Array.every()` method:

```
const commands =  [ commandA, commandB, commandC ];

button.bind( 'isEnabled' ).toMany( commands, 'isEnabled', ( ...areEnabled ) => {
    return areEnabled.every( isCommandEnabled => isCommandEnabled );
} );

```

This kind of binding can be useful, for example, when a button opens a dropdown containing some other commands’ buttons and it should be disabled when none of the commands is enabled.

<a id="ckeditor5/latest/framework/deep-dive/observables.html--releasing-the-bindings">

#### Releasing the bindings

If you do not want your object’s properties to be bound any longer, you can use the [unbind()](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-unbind) method.

You can specify the names of the properties to selectively unbind them

```
const button = new Button();
const command = editor.commands.get( 'bold' );

button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

// More bindings.
// ...

// From now on, button#isEnabled is no longer bound to the command.
button.unbind( 'isEnabled' );

```

or you can dismiss all bindings by calling the method without arguments

```
const button = new Button();
const command = editor.commands.get( 'bold' );

button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

// More bindings.
// ...

// Both #isEnabled and #isOn properties are independent back again.
// They will retain the last values determined by the bindings, though.
button.unbind();

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--decorating-object-methods">

### Decorating object methods

Decorating object methods transforms them into event–driven ones without changing their original behavior.

When a method is decorated, an event of the same name is created and fired each time the method is executed. By listening to the event it is possible to cancel the execution, change the arguments or the value returned by the method. This offers an additional flexibility, for example, giving a third–party code some way to interact with core classes that decorate their methods.

Decorating is possible using the [decorate()](../../api/module%5Futils%5Fobservablemixin-Observable.html#function-decorate) method. Decorate a `focus` method of a `Button` class you created in the [previous sections](#ckeditor5/latest/framework/deep-dive/observables.html--making-properties-observable) and see what if offers:

```
class Button extends View {
    constructor() {
        // Setting the template and bindings.
        // ...

        this.decorate( 'focus' );
    }

    /**
    * Focuses the button.
    *
    * @param {Boolean} force When `true`, the button will be focused again, even if already
    * focused in DOM.
    * @returns {Boolean} `true` when the DOM element was focused in DOM, `false` otherwise.
    */
    focus( force ) {
        console.log( `Focusing button, force argument="${ force }"` );

        // Unless forced, the button will only focus when not already focused.
        if ( force || document.activeElement != this.element ) {
            this.element.focus();

            return true;
        }

        return false;
    }
}

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--cancelling-the-execution">

#### Cancelling the execution

Because the `focus()` method is now event–driven, it can be controlled externally. For example, the focusing could be stopped for certain arguments. Note the `high` listener [priority](../../api/module%5Futils%5Fpriorities-PriorityString.html) used to intercept the default action:

```
const button = new Button();

// Render the button to create its #element.
button.render();

// The logic controlling the behavior of the button.
button.on( 'focus', ( evt, [ isForced ] ) => {
    // Disallow forcing the focus of this button.
    if ( isForced === true ) {
        evt.stop();
    }
}, { priority: 'high' } );

button.focus(); // -> 'Focusing button, force argument="undefined"'
button.focus( true ); // Nothing is logged, the execution has been stopped.

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--changing-the-returned-value">

#### Changing the returned value

It is possible to control the returned value of a decorated method using an event listener. The returned value is passed in the event data as a `return` property:

```
const button = new Button();

// Render the button to create its #element.
button.render();

// The logic controlling the behavior of the button.
button.on( 'focus', ( evt, [ isForced ] ) => {
    // Pretend the button wasn't focused if the focus was forced.
    if ( isForced === true ) {
        evt.return = false;
    }
} );

console.log( button.focus() ); // -> true
console.log( button.focus( true ) ); // -> false

```

<a id="ckeditor5/latest/framework/deep-dive/observables.html--changing-arguments-on-the-fly">

#### Changing arguments on the fly

Just like the returned value, the arguments passed to the method can be changed in the event listener. Note the `high` listener [priority](../../api/module%5Futils%5Fpriorities-PriorityString.html) of the used to intercept the default action:

```
const button = new Button();

// Render the button to create its #element.
button.render();

// The logic controlling the behavior of the button.
button.on( 'focus', ( evt, args ) => {
    // Always force the focus.
    args[ 0 ] = true;
}, { priority: 'high' } );

button.focus(); // -> 'Focusing button, force="true"'
button.focus( true ); // -> 'Focusing button, force="true"'

```

<a id="ckeditor5/latest/framework/deep-dive/schema.html">source file: "ckeditor5/latest/framework/deep-dive/schema.html"</a>

## Schema

This article assumes that you have already read the [“Schema”](#ckeditor5/latest/framework/architecture/editing-engine.html--schema) section of the [introduction to the editing engine architecture](#ckeditor5/latest/framework/architecture/editing-engine.html).

<a id="ckeditor5/latest/framework/deep-dive/schema.html--quick-recap">

### Quick recap

The editor’s schema is available in the [editor.model.schema](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#member-schema) property. It defines allowed model structures (how model elements can be nested), allowed attributes (of both elements and text nodes), and other characteristics (inline vs. block, atomicity in regards of external actions). This information is later used by editing features and the editing engine to decide how to process the model, where to enable features, etc.

Schema rules can be defined by using the [Schema#register()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-register) or the [Schema#extend()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-extend) methods. The former can be used only once for a given item name which ensures that only a single editing feature can introduce this item. Similarly, `extend()` can only be used for defined items.

Elements and attributes are checked by features separately by using the [Schema#checkChild()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-checkChild) and the [Schema#checkAttribute()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-checkAttribute) methods.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--defining-allowed-structures">

### Defining allowed structures

When a feature introduces a model element, it should register it in the schema. Besides defining that such an element may exist in the model, the feature also needs to define where this element can be placed. This information is provided by the [allowIn](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-allowIn) property of the [ModelSchemaItemDefinition](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html):

```
schema.register( 'myElement', {
    allowIn: '$root'
} );

```

This lets the schema know that `<myElement>` can be a child of `<$root>`. The `$root` element is one of the generic nodes defined by the editing framework. By default, the editor names the main root element a `<$root>`, so the above definition allows `<myElement>` in the main editor element.

In other words, this would be correct:

```
<$root>
    <myElement></myElement>
</$root>

```

While this would be incorrect:

```
<$root>
    <foo>
        <myElement></myElement>
    </foo>
</$root>

```

To declare which nodes are allowed inside the registered element, the [allowChildren](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-allowChildren) property could be used:

```
schema.register( 'myElement', {
    allowIn: '$root',
    allowChildren: '$text'
} );

```

To allow the following structure:

```
<$root>
    <myElement>
        foobar
    </myElement>
</$root>

```

Both the `[allowIn](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-allowIn)` and `[allowChildren](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-allowChildren)` properties can also be inherited from other `SchemaItemDefinition` items.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--disallowing-structures">

### Disallowing structures

The schema, in addition to allowing certain structures, can also be used to ensure some structures are explicitly disallowed. This can be achieved with the use of disallow rules.

Typically, you will use [disallowChildren](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-disallowChildren) property for that. It can be used to define which nodes are disallowed inside given element:

```
schema.register( 'myElement', {
    inheritAllFrom: '$block',
    disallowChildren: 'imageInline'
} );

```

In the example above, a new custom element should behave like any block element (paragraph, heading, etc.) but it should not be possible to insert inline images inside it.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--precedence-over-allow-rules">

#### Precedence over allow rules

In general, all `disallow` rules have higher priority than their `allow` counterparts. When we also take inheritance into the picture, the hierarchy of rules looks like this (from the highest priority):

1. `disallowChildren` / `disallowIn` from the element’s own definition.
2. `allowChildren` / `allowIn` from the element’s own definition.
3. `disallowChildren` / `disallowIn` from the inherited element’s definition.
4. `allowChildren` / `allowIn` from the inherited element’s definition.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--disallow-rules-examples">

#### Disallow rules examples

While disallowing is easy to understand for simple cases, things might start to get unclear when more complex rules are involved. Below are some examples explaining how disallowing works when rules inheriting is involved.

```
schema.register( 'baseChild' );
schema.register( 'baseParent', { allowChildren: [ 'baseChild' ] } );

schema.register( 'extendedChild', { inheritAllFrom: 'baseChild' } );
schema.register( 'extendedParent', { inheritAllFrom: 'baseParent', disallowChildren: [ 'baseChild' ] } );

```

In this case, `extendedChild` will be allowed in `baseParent` (thanks to inheriting from `baseChild`) and in `extendedParent` (as it inherits `baseParent`).

However, `baseChild` will be allowed only in `baseParent`. Although `extendedParent` inherits all rules from `baseParent`, it specifically disallows `baseChild` as part of its definition.

Below is a different example, where instead `baseChild` is extended with `disallowIn` rule:

```
schema.register( 'baseParent' );
schema.register( 'baseChild', { allowIn: 'baseParent' } );

schema.register( 'extendedParent', { inheritAllFrom: 'baseParent' } );
schema.register( 'extendedChild', { inheritAllFrom: 'baseChild' } );
schema.extend( 'baseChild', { disallowIn: 'extendedParent' } );

```

This changes how schema rules are resolved. `baseChild` will still be disallowed in `extendedParent` as before. But now, `extendedChild` will be disallowed in `extendedParent` as well. That is because it will inherit this rule from `baseChild`, and there is no other rule that would allow `extendedChild` in `extendedParent`.

Of course, you can mix `allowIn` with `disallowChildren` as well as `allowChildren` with `disallowIn`.

Finally, a situation may come up, when you want to inherit from an item which is already disallowed, but the new element should be re-allowed again. In this case, the definitions should look like this:

```
schema.register( 'baseParent', { inheritAllFrom: 'paragraph', disallowChildren: [ 'imageInline' ] } );
schema.register( 'extendedParent', { inheritAllFrom: 'baseParent', allowChildren: [ 'imageInline' ] } );

```

Here, `imageInline` is allowed in paragraph, but will not be allowed in `baseParent`. However, `extendedParent` will again re-allow it, as own definitions are more important than inherited definitions.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--defining-additional-semantics">

### Defining additional semantics

In addition to setting allowed structures, the schema can also define additional traits of model elements. By using the `is*` properties, a feature author may declare how a certain element should be treated by other features and by the engine.

Here is a table listing various model elements and their properties registered in the schema:

| Schema entry                                                                 | Properties in the [definition](#ckeditor5/latest/framework/deep-dive/schema.html--defining-allowed-structures) |                                                                                |                                                                                |                                                                                        |                                                                                  |   |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | - |
| [isBlock](#ckeditor5/latest/framework/deep-dive/schema.html--block-elements) | [isLimit](#ckeditor5/latest/framework/deep-dive/schema.html--limit-elements)                                   | [isObject](#ckeditor5/latest/framework/deep-dive/schema.html--object-elements) | [isInline](#ckeditor5/latest/framework/deep-dive/schema.html--inline-elements) | [isSelectable](#ckeditor5/latest/framework/deep-dive/schema.html--selectable-elements) | [isContent](#ckeditor5/latest/framework/deep-dive/schema.html--content-elements) |   |
| $block                                                                       | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $container                                                                   | ❌                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $blockObject                                                                 | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| $inlineObject                                                                | ❌                                                                                                              | ✅                                                                              | ✅                                                                              | ✅                                                                                      | ✅                                                                                | ✅ |
| $clipboardHolder                                                             | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $documentFragment                                                            | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $marker                                                                      | ❌                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $root                                                                        | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| $text                                                                        | ❌                                                                                                              | ❌                                                                              | ❌                                                                              | ✅                                                                                      | ❌                                                                                | ✅ |
| blockQuote                                                                   | ❌                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| bookmark                                                                     | ❌                                                                                                              | ✅                                                                              | ✅                                                                              | ✅                                                                                      | ✅                                                                                | ✅ |
| caption                                                                      | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| codeBlock                                                                    | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| heading1                                                                     | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| heading2                                                                     | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| heading3                                                                     | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| horizontalLine                                                               | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| imageBlock                                                                   | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| imageInline                                                                  | ❌                                                                                                              | ✅                                                                              | ✅                                                                              | ✅                                                                                      | ✅                                                                                | ✅ |
| listItem                                                                     | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| media                                                                        | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| mergeField                                                                   | ❌                                                                                                              | ✅                                                                              | ✅                                                                              | ✅                                                                                      | ✅                                                                                | ✅ |
| mergeFieldBlock                                                              | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| pageBreak                                                                    | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| paragraph                                                                    | ✅                                                                                                              | ❌                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| rawHtml                                                                      | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| softBreak                                                                    | ❌                                                                                                              | ❌                                                                              | ❌                                                                              | ✅                                                                                      | ❌                                                                                | ❌ |
| table                                                                        | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |
| tableRow                                                                     | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| tableCell                                                                    | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ✅                                                                                | ❌ |
| tableColumn                                                                  | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| tableColumnGroup                                                             | ❌                                                                                                              | ✅                                                                              | ❌                                                                              | ❌                                                                                      | ❌                                                                                | ❌ |
| tableOfContents                                                              | ✅                                                                                                              | ✅                                                                              | ✅                                                                              | ❌                                                                                      | ✅                                                                                | ✅ |

<a id="ckeditor5/latest/framework/deep-dive/schema.html--limit-elements">

#### Limit elements

Consider a feature like an image caption. The caption text area should construct a boundary to some internal actions:

* A selection that starts inside should not end outside.
* Pressing Backspace or Delete should not delete the area. Pressing Enter should not split the area.

It should also act as a boundary for external actions. This is mostly enforced by a selection post-fixer that ensures that a selection that starts outside, should not end inside. It means that most actions will either apply to the “outside” of such an element or to the content inside it.

Taken these characteristics, the image caption should be defined as a limit element by using the [isLimit](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isLimit) property.

```
schema.register( 'myCaption', {
    isLimit: true
} );

```

The engine and various features then check it via [Schema#isLimit()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-isLimit) and can act accordingly.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--object-elements">

#### Object elements

For an image caption like in the example above it does not make much sense to select the caption box, then copy or drag it somewhere else.

A caption without the image it describes makes little sense. The image, however, is more self-sufficient. Most likely users should be able to select the entire image (with all its internals), then copy or move it around. The [isObject](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isObject) property should be used to mark such behavior.

```
schema.register( 'myImage', {
    isObject: true
} );

```

The [Schema#isObject()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-isObject) can later be used to check this property.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--block-elements">

#### Block elements

Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc. All these elements should be marked as blocks by using [isBlock](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isBlock).

Schema items with the `isBlock` property set are (among others) affecting the [Selection#getSelectedBlocks()](../../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html#function-getSelectedBlocks) behavior and by that allow setting block level attributes like `alignment` to appropriate elements.

It is important to remember that a block should not allow another block inside. Container elements like `<blockQuote>`, which can contain other block elements, should not be marked as blocks.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--inline-elements">

#### Inline elements

In the editor, all HTML formatting elements such as `<strong>` or `<code>` are represented by text attributes. Therefore, inline model elements are not supposed to be used for these scenarios. To learn more about how text attributes work and how they are converted to inline elements in the view, see the [Attributes and inline formatting](#ckeditor5/latest/framework/deep-dive/conversion/attributes.html) guide.

Currently, the [isInline](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isInline) property is used for the `$text` token (so, text nodes) and elements such as `<softBreak>`, `<imageInline>` or placeholder elements such as described in the [Implementing an inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html) tutorial.

The support for inline elements in CKEditor 5 is so far limited to self-contained elements. Because of this, all elements marked with `isInline` should also be marked with `isObject`.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--selectable-elements">

#### Selectable elements

Elements that users can select as a whole (with all their internals) and then, for instance, copy them or apply formatting, are marked with the [isSelectable](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isSelectable) property in the schema:

```
schema.register( 'mySelectable', {
    isSelectable: true
} );

```

The [Schema#isSelectable()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-isSelectable) method can later be used to check this property.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--content-elements">

#### Content elements

You can tell content model elements from other elements by looking at their representation in the editor data (you can use [editor.getData()](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#function-getData) or [Model#hasContent()](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-hasContent) to check this out).

Elements such as images or media will **always** find their way into the editor data and this is what makes them content elements. They are marked with the [isContent](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isContent) property in the schema:

```
schema.register( 'myImage', {
    isContent: true
} );

```

The [Schema#isContent()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-isContent) method can later be used to check this property.

At the same time, elements like paragraphs, list items, or headings **are not** content elements because they are skipped in the editor output when they are empty. From the data perspective, they are transparent unless they contain other content elements (an empty paragraph is as good as no paragraph).

<a id="ckeditor5/latest/framework/deep-dive/schema.html--generic-items">

### Generic items

There are several generic items (classes of elements) available: `$root`, `$container`, `$block`, `$blockObject`, `$inlineObject`, and `$text`. They are defined as follows:

```
schema.register( '$root', {
    isLimit: true
} );

schema.register( '$container', {
    allowIn: [ '$root', '$container' ]
} );

schema.register( '$block', {
    allowIn: [ '$root', '$container' ],
    isBlock: true
} );

schema.register( '$blockObject', {
    allowWhere: '$block',
    isBlock: true,
    isObject: true
} );

schema.register( '$inlineObject', {
    allowWhere: '$text',
    allowAttributesOf: '$text',
    isInline: true,
    isObject: true
} );

schema.register( '$text', {
    allowIn: '$block',
    isInline: true,
    isContent: true
} );

```

These definitions can then be reused by features to create their own definitions in a more extensible way. For example, the [Paragraph](../../api/module%5Fparagraph%5Fparagraph-Paragraph.html) feature will define its item as:

```
schema.register( 'paragraph', {
    inheritAllFrom: '$block'
} );

```

Which translates to:

```
schema.register( 'paragraph', {
    allowWhere: '$block',
    allowContentOf: '$block',
    allowAttributesOf: '$block',
    inheritTypesFrom: '$block'
} );

```

And this can be read as:

* The `<paragraph>` element will be allowed in elements in which `<$block>` is allowed (like in `<$root>`).
* The `<paragraph>` element will allow all nodes that are allowed in `<$block>` (like `$text`).
* The `<paragraph>` element will allow all attributes allowed in `<$block>`.
* The `<paragraph>` element will inherit all `is*` properties of `<$block>` (like `isBlock`).

Thanks to the fact that the `<paragraph>` definition is inherited from `<$block>` other features can use the `<$block>` type to indirectly extend the `<paragraph>` definition. For example, the [BlockQuote](../../api/module%5Fblock-quote%5Fblockquote-BlockQuote.html) feature does this:

```
schema.register( 'blockQuote', {
    inheritAllFrom: '$container'
} );

```

Because `<$block>` is allowed in `<$container>` (see `schema.register( '$block' ...)`), despite the fact that the block quote and paragraph features know nothing about each other, paragraphs will be allowed in block quotes: the schema rules allow chaining.

Taking this even further, if anyone registers a `<section>` element (with the `allowContentOf: '$root'` rule), because `<$container>` is also allowed in `<$root>` (see `schema.register( '$container' ...)`) the `<section>` elements will allow block quotes out–of–the–box.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--relations-between-generic-items">

#### Relations between generic items

Relations between generic items (which one can be used where) can be visualized by the following abstract structure:

```
<$root>
    <$block>                <!-- example: <paragraph>, <heading1> -->
        <$text/>
        <$inlineObject/>    <!-- example: <imageInline> -->
    </$block>
    <$blockObject/>            <!-- example: <imageBlock>, <table> -->
    <$container>            <!-- example: <blockQuote> -->
        <$container/>
        <$block/>
        <$blockObject/>
    </$container>
</$root>

```

The above rules will be met for instance by such a model content:

```
<$root>
    <heading1>                <!-- inheritAllFrom: $block -->
        <$text/>            <!-- allowIn: $block -->
    </heading1>
    <paragraph>                <!-- inheritAllFrom: $block -->
        <$text/>            <!-- allowIn: $block -->
        <softBreak/>        <!-- allowWhere: $text -->
        <$text/>            <!-- allowIn: $block -->
        <imageInline/>        <!-- inheritAllFrom: $inlineObject -->
    </paragraph>
    <imageBlock>            <!-- inheritAllFrom: $blockObject -->
        <caption>            <!-- allowIn: imageBlock, allowContentOf: $block -->
            <$text/>        <!-- allowIn: $block -->
        </caption>
    </imageBlock>
    <blockQuote>                    <!-- inheritAllFrom: $container -->
        <paragraph/>                <!-- inheritAllFrom: $block -->
        <table>                        <!-- inheritAllFrom: $blockObject -->
            <tableRow>                <!-- allowIn: table -->
                <tableCell>            <!-- allowIn: tableRow, allowContentOf: $container -->
                    <paragraph>        <!-- inheritAllFrom: $block -->
                        <$text/>    <!-- allowIn: $block -->
                    </paragraph>
                </tableCell>
            </tableRow>
        </table>
    </blockQuote>
</$root>

```

Which, in turn, has these [semantics](#ckeditor5/latest/framework/deep-dive/schema.html--defining-additional-semantics):

```
<$root>                        <!-- isLimit: true -->
    <heading1>                <!-- isBlock: true -->
        <$text/>            <!-- isInline: true, isContent: true -->
    </heading1>
    <paragraph>                <!-- isBlock: true -->
        <$text/>            <!-- isInline: true, isContent: true -->
        <softBreak/>        <!-- isInline: true -->
        <$text/>            <!-- isInline: true, isContent: true -->
        <imageInline/>        <!-- isInline: true, isObject: true -->
    </paragraph>
    <imageBlock>            <!-- isBlock: true, isObject: true -->
        <caption>            <!-- isLimit: true -->
            <$text/>        <!-- isInline: true, isContent: true -->
        </caption>
    </imageBlock>
    <blockQuote>
        <paragraph/>                <!-- isBlock: true -->
        <table>                        <!-- isBlock: true, isObject: true -->
            <tableRow>                <!-- isLimit: true -->
                <tableCell>            <!-- isLimit: true -->
                    <paragraph>        <!-- isBlock: true -->
                        <$text/>    <!-- isInline: true, isContent: true -->
                    </paragraph>
                </tableCell>
            </tableRow>
        </table>
    </blockQuote>
</$root>

```

<a id="ckeditor5/latest/framework/deep-dive/schema.html--defining-advanced-rules-using-callbacks">

### Defining advanced rules using callbacks

The base [declarative SchemaItemDefinition API](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html) is by its nature limited, and some custom rules might not be possible to be implemented this way.

For this reason, it is also possible to define schema checks by providing callbacks. This gives you flexibility to implement any logic that you need.

These callbacks can be set both for child checks (model structure checks) and attribute checks.

Note that the callbacks take precedence over the rules defined through the declarative API and can overwrite these rules.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--child-checks-structure-checks">

#### Child checks (structure checks)

Using [Schema#addChildCheck()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-addChildCheck) you can provide function callbacks to implement specific advanced rules for checking the model structure.

You can provide callbacks that are fired only when a specific child is checked, or generic callbacks fired for all checks performed by the schema.

Below is an example of a specific callback, that disallows inline images inside code blocks:

```
schema.addChildCheck( context => {
    if ( context.endsWith( 'codeBlock' ) ) {
        return false;
    }
}, 'imageInline' );

```

The second parameter (`'imageInline'`) specifies that the callback will be used only if `imageInline` is being checked.

You can also use a callback to force given item to be allowed. For example, allow special `$marker` item to be allowed everywhere:

```
schema.addChildCheck( () => true, '$marker' );

```

Note that a callback may return `true`, `false`, or no value (`undefined`). If `true` or `false` is returned, the decision was made and further callbacks or declarative rules will not be checked. The item will be allowed or disallowed. If no value is returned, further checks will decide whether the item is allowed or not.

In some cases, you may need to define a generic listener that will be fired on every schema check.

For instance, to disallow all block objects (for example tables) inside a block quotes, you can define following callback:

```
schema.addChildCheck( ( context, childDefinition ) => {
    if ( context.endsWith( 'blockQuote' ) && childDefinition.isBlock && childDefinition.isObject ) {
        return false;
    }
} );

```

The above will trigger on every `checkChild()` call giving you more flexibility. However, please keep in mind that using multiple generic callbacks might negatively impact the editor performance.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--attribute-checks">

#### Attribute checks

Similarly, you can define callbacks to check whether given attribute is or is not allowed on given item.

This time, you will use [Schema#addAttributeCheck()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-addAttributeCheck) to provide the callback.

For example, allow custom attribute `headingMarker` on all headings:

```
schema.addAttributeCheck( ( context, attributeName ) => {
    const isHeading = context.last.name.startsWith( 'heading' );

    if ( isHeading ) {
        return true;
    }
}, 'headingMarker' );

```

Generic callbacks are available too. For example, disallow formatting attributes (like bold or italic) on text inside all headings:

```
schema.addAttributeCheck( ( context, attributeName ) => {
    const parent = context.getItem( context.length - 2 );
    const insideHeading = parent && parent.name.startsWith( 'heading' );

    if ( insideHeading && context.endsWith( '$text' ) && schema.getAttributeProperties( attributeName ).isFormatting ) {
        return false;
    }
} );

```

All notes related to child check callbacks apply to attribute callbacks as well.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--implementing-additional-constraints">

### Implementing additional constraints

Schema’s capabilities are limited to simple (and atomic) [Schema#checkChild()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-checkChild) and [Schema#checkAttribute()](../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-checkAttribute) checks on purpose. One may imagine that the schema should support defining more complex rules such as “element `<x>` must be always followed by `<y>`.” While it is feasible to create an API that would enable feeding the schema with such definitions, it is unfortunately unrealistic to then expect that every editing feature will consider these rules when processing the model. It is also unrealistic to expect that it will be done automatically by the schema and the editing engine themselves.

For instance, let’s get back to the “element `<x>` must be always followed by `<y>`” rule and this initial content:

```
<$root>
    <x>foo</x>
    <y>bar[bom</y>
    <z>bom]bar</z>
</$root>

```

Now imagine that the user presses the “Block quote” button. Normally it would wrap the two selected blocks (`<y>` and `<z>`) with a `<blockQuote>` element:

```
<$root>
    <x>foo</x>
    <blockQuote>
        <y>bar[bom</y>
        <z>bom]bar</z>
    </blockQuote>
</$root>

```

However, it turns out that this creates an incorrect structure – `<x>` is not followed by `<y>` anymore.

What should happen instead? There are at least 4 possible solutions: the block quote feature should not be applicable in such a context, someone should create a new `<y>` right after `<x>`, `<x>` should be moved inside `<blockQuote>` together with `<y>` or vice versa.

While this is a relatively simple scenario (unlike most real-time collaborative editing scenarios), it turns out that it is already hard to say what should happen and who should react to fix this content.

Therefore, if your editor needs to implement such rules, you should do that through [model’s post-fixers](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#function-registerPostFixer) fixing incorrect content or actively prevent such situations (for example, by disabling certain features). It means that these constraints will be defined specifically for your scenario by your code which makes their implementation much easier.

To sum up, the answer to who and how should implement additional constraints is: your features or your editor through the CKEditor 5 API.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--who-checks-the-schema">

### Who checks the schema?

The CKEditor 5 API exposes many ways to work on (change) the model. It can be done [through the writer](#ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-model), via methods like [Model#insertContent()](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent), via commands, and so on.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--low-level-apis">

#### Low-level APIs

The lowest-level API is the writer (to be precise, there are also raw operations below, but they are used for special cases only). It allows applying atomic changes to the content like inserting, removing, moving or splitting nodes, setting and removing an attribute, etc. It is important to know that the **writer does not prevent from applying changes that violate rules defined in the schema**.

The reason for this is that when you implement a command or any other feature you may need to perform multiple operations to do all the necessary changes. The state in the meantime (between these atomic operations) may be incorrect. The writer must allow that.

For instance, you need to move `<foo>` from `<$root>` to `<bar>` and (at the same time) rename it to `<oof>`. But the schema defines that `<oof>` is not allowed in `<$root>` and `<foo>` is disallowed in `<bar>`. If the writer checked the schema, it would complain regardless of the order of `rename` and `move` operations.

You can argue that the engine could handle this by checking the schema at the end of a [Model#change() block](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-change) (it works like a transaction – the state needs to be correct at the end of it). This approach, however, was not adopted, as there are the following problems:

* How to fix the content after a transaction is committed? It is impossible to implement a reasonable heuristic that would not break the content from the user’s perspective.
* The model can become invalid during real-time collaborative changes. Operational Transformation, while implemented by us in a rich form (with 11 types of operations instead of the base 3), ensures conflict resolution and eventual consistency, but not the model’s validity.

Therefore, we chose to handle such situations on a case-by-case basis, using more expressive and flexible [model’s post-fixers](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#function-registerPostFixer). Additionally, we moved the responsibility of checking the schema to features. They can make a lot better decisions before making changes. You can read more about this in the [“Implementing additional constraints”](#ckeditor5/latest/framework/deep-dive/schema.html--implementing-additional-constraints) section above.

<a id="ckeditor5/latest/framework/deep-dive/schema.html--high-level-apis">

#### High-level APIs

What about other, higher-level methods? **We recommend that all APIs built on top of the writer should check the schema.**

For instance, the [Model#insertContent()](../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) method will make sure that inserted nodes are allowed in the place of their insertion. It may also attempt to split the insertion container (if allowed by the schema) if that will make the element to insert allowed, and so on.

Similarly, commands – if implemented correctly – [get disabled](../../api/module%5Fcore%5Fcommand-Command.html#member-isEnabled) if they should not be executed in the current place.

Finally, the schema plays a crucial role during the conversion from the view to the model (also called “upcasting”). During this process converters decide whether they can convert specific view elements or attributes to the given positions in the model. Thanks to that if you tried to load incorrect data to the editor or when you paste content copied from another website, the structure and attributes of the data get adjusted to the current schema rules.

<a id="ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html">source file: "ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html"</a>

## Implementing a custom editor creator

The flexible architecture of CKEditor 5 allows creating custom editors. Not only the [theme styling can be changed](#ckeditor5/latest/examples/framework/theme-customization.html) or the [UI redesigned](#ckeditor5/latest/examples/framework/custom-ui.html) but also the entire editor initialization process can be modified allowing to create new editor types. Thanks to that, apart from the standard editors (like [classic](#ckeditor5/latest/examples/builds/classic-editor.html), [inline](#ckeditor5/latest/examples/builds/inline-editor.html), [balloon](#ckeditor5/latest/examples/builds/balloon-editor.html) or [document](#ckeditor5/latest/examples/builds/document-editor.html)), custom types like a [**multi-root editor**](#ckeditor5/latest/examples/builds/multi-root-editor.html) can be created.

This guide goes through the process of implementing a custom, multi-root editor. You can check out the [demo of the multi-root editor](#ckeditor5/latest/examples/builds/multi-root-editor.html) too.

<a id="ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html--editor-class">

### Editor class

The `*Editor` class is the main class of each editor type. It initializes the whole editor and its UI parts. The custom creator class should extend the [base Editor class](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html). For a multi-root editor, it may look like below:

<a id="ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html--editorui-class">

### EditorUI class

The `*EditorUI` class is the main UI class that initializes UI components (the main view and the toolbar) and sets up mechanisms like [focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class) or placeholder management. The custom `*EditorUI` class should extend the [base EditorUI class](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html) like below:

<a id="ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html--editoruiview-class">

### EditorUIView class

Finally, the `*EditorUIView` class is responsible for registering and handling all editable elements and for creating the editor toolbar. The custom `*EditorUIView` class should extend the [base EditorUIView class](../../../api/module%5Fui%5Feditorui%5Feditoruiview-EditorUIView.html):

<a id="ckeditor5/latest/framework/deep-dive/ui/custom-editor-creator.html--initializing-custom-editor-instance">

### Initializing custom editor instance

Now with the multi-root editor creator ready, you can create a fully usable editor instance.

With HTML like:

```
<div id="toolbar"></div>

<header id="header">
    <h2>Gone traveling</h2>
    <h3>Monthly travel news and inspiration</h3>
</header>

<div id="content">
    <h3>Destination of the Month</h3>

    <h4>Valletta</h4>

    <figure class="image image-style-align-right">
        <img alt="Picture of a sunlit facade of a Maltan building." src="../../../assets/img/malta.jpg">
        <figcaption>It's siesta time in Valletta.</figcaption>
    </figure>

    <p>The capital city of <a href="https://en.wikipedia.org/wiki/Malta" target="_blank" rel="external">Malta</a> is the top destination this summer. It’s home to a cutting-edge contemporary architecture, baroque masterpieces, delicious local cuisine, and at least 8 months of sun. It’s also a top destination for filmmakers, so you can take a tour through locations familiar to you from Game of Thrones, Gladiator, Troy and many more.</p>
</div>

<div class="demo-row">
    <div class="demo-row__half">
        <div id="footer-left">
            <h3>The three greatest things you learn from traveling</h3>
            <p><a href="#">Find out more</a></p>
        </div>
    </div>

    <div class="demo-row__half">
        <div id="footer-right">
            <h3>Walking the capitals of Europe: Warsaw</h3>
            <p><a href="#">Find out more</a></p>
        </div>
    </div>
</div>

```

You can initialize the editor with the code below:

```
MultirootEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Essentials, Paragraph, Heading, Bold, Italic, List, Link, BlockQuote, Image, ImageCaption,
            ImageStyle, ImageToolbar, ImageUpload, Table, TableToolbar, MediaEmbed ],
        toolbar: [ 'heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'uploadImage', 'blockQuote',
            'insertTable', 'mediaEmbed', 'undo', 'redo' ],
        image: {
            toolbar: [ 'toggleImageCaption', 'imageTextAlternative', '|', 'imageStyle:inline', 'imageStyle:wrapText', 'imageStyle:breakText' ],
        },
        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        },
        roots: {
            header: {
                element: document.querySelector( '#header' ),
                placeholder: 'Header text goes here'
            },
            content: {
                element: document.querySelector( '#content' ),
                placeholder: 'Type content here'
            },
            footerleft: {
                element: document.querySelector( '#footer-left' ),
                placeholder: 'Left footer content'
            },
            footerright: {
                element: document.querySelector( '#footer-right' ),
                placeholder: 'Right footer content'
            }
        },
    } )
    .then( newEditor => {
        document.querySelector( '#toolbar' ).appendChild( newEditor.ui.view.toolbar.element );

        window.editor = newEditor;
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

This will create the exact same editor as the one used on the [multi-root editor editor example page](#ckeditor5/latest/examples/builds/multi-root-editor.html).

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html">source file: "ckeditor5/latest/framework/deep-dive/ui/document-editor.html"</a>

## Document editor

The [document editor example](#ckeditor5/latest/examples/builds/document-editor.html) showcases the document editor designed for document editing with a customized UI representing the layout of a sheet of paper. It was created on top of the [DecoupledEditor](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) class and makes the best of what it offers: the freedom to choose the location of the crucial UI elements in the application.

In this tutorial, you will learn how to create your own document editor with a customized user interface, step–by–step.

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html--the-editor">

### The editor

Document editor can be created using the existing data container in the DOM. It can also accept a raw data string and create the editable by itself. To get the output data, use the [getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method.

You may have noticed that you have to make sure the editor UI is injected into your application after it fires the [EditorUI#ready](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#event-ready) event. The toolbar element can be found under `editor.ui.view.toolbar.element`.

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html--the-user-interface">

### The user interface

The code you have just created will run the editor but the user interface is still missing. Start off with a basic HTML structure to host the editor components (the toolbar and the editable).

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html--html">

#### HTML

The following structure has two containers that correspond to the configuration you have just used. The editor will inject the toolbar and the editable into respective containers as it starts.

```
<div class="document-editor">
    <div class="document-editor__toolbar"></div>
    <div class="document-editor__editable-container">
        <div class="document-editor__editable">
            <p>The initial editor data.</p>
        </div>
    </div>
</div>

```

The `<div class="document-editor">...</<div>` element is the outermost container of the document editor and, although not mandatory, it is recommended to use it to keep things together.

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html--styles">

#### Styles

Styles are what the document editor needs to materialize. Begin with the styles of the main container:

```
.document-editor {
    border: 1px solid var(--ck-color-base-border);
    border-radius: var(--ck-border-radius);

    /* Set vertical boundaries for the document editor. */
    max-height: 700px;

    /* This element is a flex container for easier rendering. */
    display: flex;
    flex-flow: column nowrap;
}

```

Then, make the toolbar look like it floats over the “page”:

```
.document-editor__toolbar {
    /* Make sure the toolbar container is always above the editable. */
    z-index: 1;

    /* Create the illusion of the toolbar floating over the editable. */
    box-shadow: 0 0 5px hsla( 0,0%,0%,.2 );

    /* Use the CKEditor CSS variables to keep the UI consistent. */
    border-bottom: 1px solid var(--ck-color-toolbar-border);
}

/* Adjust the look of the toolbar inside the container. */
.document-editor__toolbar .ck-toolbar {
    border: 0;
    border-radius: 0;
}

```

The editable should look like a sheet of paper, centered in its scrollable container:

```
/* Make the editable container look like the inside of a native word processor application. */
.document-editor__editable-container {
    padding: calc( 2 * var(--ck-spacing-large) );
    background: var(--ck-color-base-foreground);

    /* Make it possible to scroll the "page" of the edited content. */
    overflow-y: scroll;
}

.document-editor__editable-container .ck-editor__editable {
    /* Set the dimensions of the "page". */
    width: 15.8cm;
    min-height: 21cm;

    /* Keep the "page" off the boundaries of the container. */
    padding: 1cm 2cm 2cm;

    border: 1px hsl( 0,0%,82.7% ) solid;
    border-radius: var(--ck-border-radius);
    background: white;

    /* The "page" should cast a slight shadow (3D illusion). */
    box-shadow: 0 0 5px hsla( 0,0%,0%,.1 );

    /* Center the "page". */
    margin: 0 auto;
}

```

All you need to do now is style the actual content of the editor. Start with defining some basic font styles:

```
/* Set the default font for the "page" of the content. */
.document-editor .ck-content,
.document-editor .ck-heading-dropdown .ck-list .ck-button__label {
    font: 16px/1.6 "Helvetica Neue", Helvetica, Arial, sans-serif;
}

```

Then focus on headings and paragraphs. Note that what the users see in the headings dropdown should correspond to the actual edited content for the best user experience.

```
/* Adjust the headings dropdown to host some larger heading styles. */
.document-editor .ck-heading-dropdown .ck-list .ck-button__label {
    line-height: calc( 1.7 * var(--ck-line-height-base) * var(--ck-font-size-base) );
    min-width: 6em;
}

/* Scale down all heading previews because they are way too big to be presented in the UI.
Preserve the relative scale, though. */
.document-editor .ck-heading-dropdown .ck-list .ck-button:not(.ck-heading_paragraph) .ck-button__label {
    transform: scale(0.8);
    transform-origin: left;
}

/* Set the styles for "Heading 1". */
.document-editor .ck-content h2,
.document-editor .ck-heading-dropdown .ck-heading_heading1 .ck-button__label {
    font-size: 2.18em;
    font-weight: normal;
}

.document-editor .ck-content h2 {
    line-height: 1.37em;
    padding-top: .342em;
    margin-bottom: .142em;
}

/* Set the styles for "Heading 2". */
.document-editor .ck-content h3,
.document-editor .ck-heading-dropdown .ck-heading_heading2 .ck-button__label {
    font-size: 1.75em;
    font-weight: normal;
    color: hsl( 203, 100%, 50% );
}

.document-editor .ck-heading-dropdown .ck-heading_heading2.ck-on .ck-button__label {
    color: var(--ck-color-list-button-on-text);
}

/* Set the styles for "Heading 2". */
.document-editor .ck-content h3 {
    line-height: 1.86em;
    padding-top: .171em;
    margin-bottom: .357em;
}

/* Set the styles for "Heading 3". */
.document-editor .ck-content h4,
.document-editor .ck-heading-dropdown .ck-heading_heading3 .ck-button__label {
    font-size: 1.31em;
    font-weight: bold;
}

.document-editor .ck-content h4 {
    line-height: 1.24em;
    padding-top: .286em;
    margin-bottom: .952em;
}

/* Set the styles for "Paragraph". */
.document-editor .ck-content p {
    font-size: 1em;
    line-height: 1.63em;
    padding-top: .5em;
    margin-bottom: 1.13em;
}

```

A finishing touch that makes the block quotes more sophisticated and the styling is complete.

```
/* Make the block quoted text serif with some additional spacing. */
.document-editor .ck-content blockquote {
    font-family: Georgia, serif;
    margin-left: calc( 2 * var(--ck-spacing-large) );
    margin-right: calc( 2 * var(--ck-spacing-large) );
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/document-editor.html--summary">

### Summary

The document editor is ready to use. Still, you may want to configure some features like [highlight](../../../api/module%5Fhighlight%5Fhighlightconfig-HighlightConfig.html), [font size](../../../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html) or [font family](../../../api/module%5Ffont%5Ffontconfig-FontFamilyConfig.html) for the best editing experience.

Thanks to the [DecoupledEditor](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) used as a foundation, you can experiment and create custom user interface layouts quickly while preserving the feature set, accessibility support (for example, [keyboard navigation](#ckeditor5/latest/features/accessibility.html--keyboard-shortcuts) in the toolbar), and more.

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html">source file: "ckeditor5/latest/framework/deep-dive/ui/external-ui.html"</a>

## Third-party UI

CKEditor 5 is a modular editing framework that allows various flexible configurations. This includes the usage of a third–party user interface on top of the base editor classes.

In this guide, a [classic-like](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor) editor will be bound to a completely separate, existing UI created in [Bootstrap](http://getbootstrap.com/), providing the basic structure and toolbar items necessary to start editing.

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--readying-the-editor-side">

### Readying the editor side

The editor types, such as the [classic](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor) or [inline editor](#ckeditor5/latest/getting-started/setup/editor-types.html--inline-editor), have a dedicated default user interface and a theme. However, only a limited subset of features is required to create an editor instance bound to a Bootstrap UI. You need to import them first:

After importing the basic editor components, you can define the custom `BootstrapEditor` class that extends the [Editor](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html):

```
// Extending the Editor class, which brings the base editor API.
export default class BootstrapEditor extends ElementApiMixin( Editor ) {
    constructor( element, config ) {
        super( config );

        // Remember the element the editor is created with.
        this.sourceElement = element;

        // Create the ("main") root element of the model tree.
        this.model.document.createRoot();

        // The UI layer of the editor.
        this.ui = new BootstrapEditorUI( this );

        // When editor#element is a textarea inside a form element,
        // the content of this textarea will be updated on form submit.
        attachToForm( this );
    }

    destroy() {
        // When destroyed, the editor sets the output of editor#getData() into editor#element...
        this.updateSourceElement();

        // ...and destroys the UI.
        this.ui.destroy();

        return super.destroy();
    }

    static create( element, config ) {
        return new Promise( resolve => {
            const editor = new this( element, config );

            resolve(
                editor.initPlugins()
                    // Initialize the UI first. See the BootstrapEditorUI class to learn more.
                    .then( () => editor.ui.init( element ) )
                    // Fill the editable with the initial data.
                    .then( () => editor.data.init( getDataFromElement( element ) ) )
                    // Fire the `editor#ready` event that announce the editor is complete and ready to use.
                    .then( () => editor.fire( 'ready' ) )
                    .then( () => editor )
            );
        } );
    }
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--creating-the-bootstrap-ui">

### Creating the Bootstrap UI

Although the editor is ready to use, it is just a bare editable area – that is not of much use to the users. You need to give it an actual interface with the toolbar and buttons.

With the Bootstrap framework loaded in the web page, you can define the actual UI of the editor in HTML:

```
<!-- The outermost container of the editor. -->
<div class="ck-editor">
    <!-- The toolbar of the editor. -->
    <div class="btn-toolbar" role="toolbar" aria-label="Editor toolbar">
        <!-- The headings dropdown. -->
        <div class="btn-group mr-2" role="group" aria-label="Headings">
            <div class="dropdown" id="heading">
             <button class="btn btn-primary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span>Headings</span></button>
             <div class="dropdown-menu" aria-labelledby="heading-button"></div>
            </div>
        </div>

        <!-- Basic styles buttons. -->
        <div class="btn-group mr-2" role="group" aria-label="Basic styles">
            <button type="button" class="btn btn-primary btn-sm" id="bold">B</button>
            <button type="button" class="btn btn-primary btn-sm" id="italic">I</button>
            <button type="button" class="btn btn-primary btn-sm" id="underline">U</button>
        </div>

        <!-- Undo and redo buttons. -->
        <div class="btn-group mr-2" role="group" aria-label="Undo">
            <button type="button" class="btn btn-primary btn-sm" id="undo">&larr;</button>
            <button type="button" class="btn btn-primary btn-sm" id="redo">&rarr;</button>
        </div>
    </div>

    <!-- The container with the data of the editor. -->
    <div id="editor">
        <p>Hello world!</p>
    </div>
</div>

```

Although Bootstrap provides most of the CSS, it does not come with styles dedicated for [WYSIWYG](https://en.wikipedia.org/wiki/WYSIWYG) text editors and some tweaking is needed:

```
/* Give the editor some space and limits using a border. */
.ck-editor {
    margin: 1em 0;
    border: 1px solid hsla(0, 0%, 0%, 0.1);
    border-radius: 4px;
}

/* Adding internal spacing, border and background to the toolbar.  */
.ck-editor .btn-toolbar {
    padding: .5rem;
    background: hsl(240, 14%, 97%);
    border-bottom: 1px solid hsla(0, 0%, 0%, 0.1);
}

/* Tweaking the editable area for better readability. */
.ck-editor .ck-editor__editable {
    padding: 2em 2em 1em;
    overflow: auto;
}

/* When in read–only mode, the editable should fade out. */
.ck-editor .ck-editor__editable.ck-read-only {
    background: hsl(0, 0%, 98%);
    color: hsl(0, 0%, 47%);
}

/* Make sure the headings dropdown button does not change its size
as different headings are selected. */
.ck-editor .dropdown-toggle span {
    display: inline-block;
    width: 100px;
    text-align: left;
    overflow: hidden;
    text-overflow: ellipsis;
    vertical-align: bottom;
}

/* Make the headings dropdown items visually distinctive. */
.ck-editor .heading-item_heading1 { font-size: 1.5em; }
.ck-editor .heading-item_heading2 { font-size: 1.3em; }
.ck-editor .heading-item_heading3 { font-size: 1.1em; }

.ck-editor [class*="heading-item_"] {
    line-height: 22px;
    padding: 10px;
}

.ck-editor [class*="heading-item_heading"] {
  font-weight: bold;
}

/* Give the basic styles buttons the icon–like look and feel. */
.ck-editor #bold { font-weight: bold; }
.ck-editor #italic { font-style: italic; }
.ck-editor #underline { text-decoration: underline; }

```

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--binding-the-ui-with-the-editor">

### Binding the UI with the editor

At this stage, you should bind the editor created at the beginning of this guide with the Bootstrap UI defined in HTML. All the UI logic will be wrapped into a separate class matching the `EditorUI` [interface](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html). You may have noticed this line in the constructor of the `BootstrapEditor`:

```
this.ui = new BootstrapEditorUI( this );

```

Define the `BootstrapEditorUI` and then have a closer look at the content of the class:

```
// The class organizing the UI of the editor, binding it with existing Bootstrap elements in the DOM.
class BootstrapEditorUI extends EditorUI {
    constructor( editor ) {
        super( editor );

        // A helper to easily replace the editor#element with editor.editable#element.
        this._elementReplacer = new ElementReplacer();

        // The global UI view of the editor. It aggregates various Bootstrap DOM elements.
        const view = this._view = new EditorUIView( editor.locale );

        // This is the main editor element in the DOM.
        view.element = $( '.ck-editor' );

        // This is the editable view in the DOM. It will replace the data container in the DOM.
        view.editable = new InlineEditableUIView( editor.locale, editor.editing.view );

        // References to the dropdown elements for further usage. See #_setupBootstrapHeadingDropdown.
        view.dropdownMenu = view.element.find( '.dropdown-menu' );
        view.dropdownToggle = view.element.find( '.dropdown-toggle' );

        // References to the toolbar buttons for further usage. See #_setupBootstrapToolbarButtons.
        view.toolbarButtons = {};

        [ 'bold', 'italic', 'underline', 'undo', 'redo' ].forEach( name => {
            // Retrieve the jQuery object corresponding with the button in the DOM.
            view.toolbarButtons[ name ] = view.element.find( `#${ name }` );
        } );
    }

    // All EditorUI subclasses should expose their view instance
    // so other UI classes can access it if necessary.
    get view() {
        return this._view;
    }

    init( replacementElement ) {
        const editor = this.editor;
        const view = this.view;
        const editingView = editor.editing.view;

        // Make sure the EditorUIView is rendered. This will, for instance, create a place for UI elements
        // like floating panels detached from the main editor UI in DOM.
        this._view.render();

        // Create an editing root in the editing layer. It will correspond with the
        // document root created in the constructor().
        const editingRoot = editingView.document.getRoot();

        // The editable UI and editing root should share the same name.
        view.editable.name = editingRoot.rootName;

        // Render the editable component in the DOM first.
        view.editable.render();

        const editableElement = view.editable.element;

        // Register editable element so it is available via getEditableElement() method.
        this.setEditableElement( view.editable.name, editableElement );

        // Let the editable UI element respond to the changes in the global editor focus tracker
        // and let the focus tracker know about the editable element.
        this.focusTracker.add( editableElement );
        view.editable.bind( 'isFocused' ).to( this.focusTracker );

        // Bind the editable UI element to the editing view, making it an end– and entry–point
        // of the editor's engine. This is where the engine meets the UI.
        editingView.attachDomRoot( editableElement );

        // Setup the existing, external Bootstrap UI so it works with the rest of the editor.
        this._setupBootstrapToolbarButtons();
        this._setupBootstrapHeadingDropdown();

        // Replace the editor#element with editor.editable#element.
        this._elementReplacer.replace( replacementElement, editableElement );

        // Tell the world that the UI of the editor is ready to use.
        this.fire( 'ready' );
    }

    destroy() {
        super.destroy();

        // Restore the original editor#element.
        this._elementReplacer.restore();

        // Destroy the view.
        this._view.editable.destroy();
        this._view.destroy();
    }

    // This method activates Bold, Italic, Underline, Undo and Redo buttons in the toolbar.
    _setupBootstrapToolbarButtons() {
        // Implementation details are in the following snippets.
        // ...
    }

    // This method activates the headings dropdown in the toolbar.
    _setupBootstrapHeadingDropdown() {
        // Implementation details are in the following snippets.
        // ...
    }
}

```

Almost every feature in the editor defines some command, for example, [HeadingCommand](../../../api/module%5Fheading%5Fheadingcommand-HeadingCommand.html) or [UndoCommand](../../../api/module%5Fundo%5Fundocommand-UndoCommand.html). Commands can be executed:

```
editor.execute( 'undo' );

```

They also come with default observable properties like `value` and `isEnabled`. These are the entry points when it comes to creating a custom user interface because their values represent the actual state of the editor. You can follow them in simple event listeners:

```
const command = editor.commands.get( 'undo' );

command.on( 'change:isEnabled', ( evt, name, isEnabled ) => {
    if ( isEnabled ) {
        console.log( 'Whoa, you can undo some stuff now.' );
    } else {
        console.log( 'There is nothing to undo in the editor.' );
    }
} );

```

Knowing that, fill out the missing methods of the `BootstrapEditorUI`.

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--binding-the-buttons-to-editor-commands">

#### Binding the buttons to editor commands

`_setupBootstrapToolbarButtons()` is a method that binds Bootstrap toolbar buttons to the editor features (commands). It activates the corresponding editor commands upon clicking and makes the buttons listen to the state of the commands to update their CSS classes:

```
// This method activates Bold, Italic, Underline, Undo and Redo buttons in the toolbar.
_setupBootstrapToolbarButtons() {
    const editor = this.editor;

    for ( const name in this.view.toolbarButtons ) {
        // Retrieve the editor command corresponding with the ID of the button in the DOM.
        const command = editor.commands.get( name );
        const button = this.view.toolbarButtons[ name ];

        // Clicking the buttons should execute the editor command...
        button.click( () => editor.execute( name ) );

        // ...but it should not steal the focus so the editing is uninterrupted.
        button.mousedown( evt => evt.preventDefault() );

        const onValueChange = () => {
            button.toggleClass( 'active', command.value );
        };

        const onIsEnabledChange = () => {
            button.attr( 'disabled', () => !command.isEnabled );
        };

        // Commands can become disabled, e.g. when the editor is read-only.
        // Make sure the buttons reflect this state change.
        command.on( 'change:isEnabled', onIsEnabledChange );
        onIsEnabledChange();

        // Bold, Italic and Underline commands have a value that changes
        // when the selection starts in an element the command creates.
        // The button should indicate that e.g. you are editing text which is already bold.
        if ( !new Set( [ 'undo', 'redo' ] ).has( name ) ) {
            command.on( 'change:value', onValueChange );
            onValueChange();
        }
    }
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--binding-the-dropdown-to-the-heading-commands">

#### Binding the dropdown to the heading commands

The dropdown in the toolbar is a more complex case.

First, it must be populated with heading options for the users to select from. Then, clicking each option must execute a related heading command in the editor. Finally, the dropdown button and the dropdown menu items must reflect the state of the editor, for example, when the selection lands in a heading, a proper menu item should become active and the button should show the name of the heading level.

```
// This method activates the headings dropdown in the toolbar.
_setupBootstrapHeadingDropdown() {
    const editor = this.editor;
    const dropdownMenu = this.view.dropdownMenu;
    const dropdownToggle = this.view.dropdownToggle;

    // Retrieve the editor commands for heading and paragraph.
    const headingCommand = editor.commands.get( 'heading' );
    const paragraphCommand = editor.commands.get( 'paragraph' );

    // Create a dropdown menu entry for each heading configuration option.
    editor.config.get( 'heading.options' ).map( option => {
        // Check if options is a paragraph or a heading as their commands differ slightly.
        const isParagraph = option.model === 'paragraph';

        // Create the menu item DOM element.
        const menuItem = $(
            `<a href="#" class="dropdown-item heading-item_${ option.model }">` +
                `${ option.title }` +
            '</a>'
        );

        // Upon click, the dropdown menu item should execute the command and focus
        // the editing view to keep the editing process uninterrupted.
        menuItem.click( () => {
            const commandName = isParagraph ? 'paragraph' : 'heading';
            const commandValue = isParagraph ? undefined : { value: option.model };

            editor.execute( commandName, commandValue );
            editor.editing.view.focus();
        } );

        dropdownMenu.append( menuItem );

        const command = isParagraph ? paragraphCommand : headingCommand;

        // Make sure the dropdown and its items reflect the state of the
        // currently active command.
        const onValueChange = isParagraph ? onValueChangeParagraph : onValueChangeHeading;
        command.on( 'change:value', onValueChange );
        onValueChange();

        // Heading commands can become disabled, e.g. when the editor is read-only.
        // Make sure the UI reflects this state change.
        command.on( 'change:isEnabled', onIsEnabledChange );

        onIsEnabledChange();

        function onValueChangeHeading() {
            const isActive = !isParagraph && command.value === option.model;

            if ( isActive ) {
                dropdownToggle.children( ':first' ).text( option.title );
            }

            menuItem.toggleClass( 'active', isActive );
        }

        function onValueChangeParagraph() {
            if ( command.value ) {
                dropdownToggle.children( ':first' ).text( option.title );
            }

            menuItem.toggleClass( 'active', command.value );
        }

        function onIsEnabledChange() {
            dropdownToggle.attr( 'disabled', () => !command.isEnabled );
        }
    } );
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/external-ui.html--running-the-editor">

### Running the editor

When the editor classes and the user interface are ready, it is time to run the editor. Just make sure all the plugins are loaded and the right DOM element is passed to `BootstrapEditor#create`:

```
BootstrapEditor.create( $( '#editor' ).get( 0 ), {
    plugins: [
        Clipboard, Enter, Typing, Paragraph,
        BoldEditing, ItalicEditing, UnderlineEditing, HeadingEditing, UndoEditing
    ]
} )
.then( editor => {
    window.editor = editor;
} )
.catch( err => {
    console.error( err.stack );
} );

```

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html">source file: "ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html"</a>

## Deep dive into focus tracking

**Focus is where all the keyboard interactions (events) take place.** It is an essential concept for any piece of a web page operated with a keyboard, be it a physical keyboard of your laptop or a software keyboard of your smartphone. And CKEditor 5 being a rich text editor is no exception here.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--what-is-focus-and-why-it-matters-for-ckeditor">

### What is focus and why it matters for CKEditor?

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--what-is-focus">

#### What is focus?

Every time you click a text field or an editor, it automatically prepares to accept your text. It is no longer just a static container for letters but something you can interact with using your keyboard. And you know it because you can see the familiar blinking caret somewhere inside of it. This subtle action called a **focus change** takes place hundreds of times every day as you navigate web pages, type your search queries, chat with your friends and fill in checkout forms when online shopping.

Focusing text fields feels so natural we usually do not give it much thought. But without this simple action, there would be no way to type text. Where would it go if there was no focused field? Focus informs the software about your intentions and it is synonymous with the **context**.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-ckeditor">

#### Focus in CKEditor

CKEditor is more than a simple text field. Yes, it has the main space where you type your text but other places also allow you to type, for instance, a link URL field or a form with plenty of inputs allowing you to configure the look of a table.

And when many places accept focus, there must be some systems out there to discover and manage it. These systems work, for instance, so you will not find yourself in a situation where CKEditor 5 loses focus (or gets **blurred**) and you cannot type your text. Or they make sure you can see and use the editor toolbar as long as you keep editing. These are just a few examples of why focus management systems are necessary. Now it should also be clear that they are essential for the editing experience.

In the following chapters of this guide, we will explain how these systems work, what makes CKEditor “focusable”, and how to develop new editor features so they fit into the existing focus management systems and patterns:

* [**The first section**](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-engine) explains how the editor [engine](#ckeditor5/latest/framework/architecture/editing-engine.html) manages focus and what tools exist there to help you out when developing new features.
* In [**the second section**](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-ui), we will show you how the [user interface](#ckeditor5/latest/framework/architecture/ui-library.html) of the editor tracks focus and how various UI components take advantage of that, for instance, to provide accessibility.
* In [**the last part**](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-state-analysis), we will use the knowledge from previous sections in a real–life scenario and analyze how all these tools and systems work together.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-engine">

### Focus in the editor engine

The main editable area of CKEditor 5 WYSIWYG editor can be focused thanks to the [contenteditable](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable%5Fcontent) DOM attribute. This attribute tells the web browser that a web page element can be edited like any other text field, which also means it must be able to receive focus.

Each root of the editing view has the `contenteditable` attribute. The editing view uses the [FocusObserver](../../../api/module%5Fengine%5Fview%5Fobserver%5Ffocusobserver-FocusObserver.html) (learn more about [view observers](#ckeditor5/latest/framework/architecture/editing-engine.html--observers)) to track focus in editable elements by listening to native DOM `focus` and `blur` events coming from them.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--checking-if-the-view-document-is-focused">

#### Checking if the view document is focused

You can check if the view document is focused using its [observable](#ckeditor5/latest/framework/deep-dive/observables.html) [isFocused](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#member-isFocused) property. Create an editor instance and execute the following code:

```
console.log( editor.editing.view.document.isFocused );

```

If you run this snippet from the web browser’s developer console, it should return `false` unless you managed to keep the editor focused (for example, by running a debugger and freezing the DOM). This happens because the editor loses focus the moment you switch to developer tools to execute the snippet.

How do you know `isFocused` actually works? Since it is observable, you can see how it changes live:

```
editor.editing.view.document.on( 'change:isFocused', ( evt, data, isFocused ) => {
    console.log( `View document is focused: ${ isFocused }.` );
} );

```

Click the editable area of the editor and then click somewhere else – the `isFocused` property will change its value when you do that. The same will also happen if you run an editor with [**multiple editing roots**](#ckeditor5/latest/examples/builds/multi-root-editor.html) and navigate across them.

To spice things up even more, you should also know `isFocused` will change when you focus any [**nested editable**](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html) in the content (take, for example, a [caption of an image](#ckeditor5/latest/features/images/images-captions.html)). Sounds weird, right? This is because every nested editable in the content has the `contenteditable` attribute, too, and for the web browser moving your caret inside it means the main editable element is blurred and the nested one is focused.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--how-to-focus-the-editor">

#### How to focus the editor?

The simplest way to focus the editor is to call the [editor.focus()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-focus) method.

However, you may wish to explicitly focus the editable area of CKEditor 5 when a certain action is executed (for example, a button is clicked). To do that, use the [focus()](../../../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-focus) method of the editing view:

```
editor.editing.view.focus();

```

This snippet focuses the editable that has the selection. If the editor has not been focused yet, this will focus the first editable. If an editor has many editing roots and the user was editing content, focus will be brought back where the user left off.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-ui">

### Focus in the editor UI

If you read the [previous section](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-engine) of this guide you should know that there is already a layer responsible for tracking focus implemented in the [editor engine](#ckeditor5/latest/framework/architecture/editing-engine.html). But because the [editor framework is modular](#ckeditor5/latest/framework/architecture/intro.html), this layer is only concerned by the focus in editable roots of the editor and it knows nothing of the user interface. This granularity makes it possible, for instance, to create a fully–functioning editor without the UI.

As for the user interface of CKEditor 5, it is a composition of multiple components [organized as a tree](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree). This tree determines not only the logical structure of the UI (a toolbar has a dropdown, a dropdown has a button, a button has an icon, etc.) but also its behavior, and that includes tracking and maintaining focus as the user navigates and interacts with various pieces of the interface.

To sum up, there are two main reasons why focus is being tracked separately on the UI level:

* **To make sure the editor (as a whole) never loses focus unless the user wants it to.**  
For instance, take a look at the [inline editor](#ckeditor5/latest/examples/builds/inline-editor.html). As long as the user edits text in the main editable area or configures its properties in any pop-up, dropdown, or panel, the main editor toolbar must remain visible (because the focus is somewhere in the UI). Only when the user finishes editing and moves somewhere else on a web page, the toolbar can disappear.
* **To make the UI accessible to users who navigate it using screen readers and other assistive technologies.**  
These users not only write text using the keyboard but also use it to navigate across toolbar buttons, panels, dropdowns, etc. The UI of the editor must constantly keep track of which component is currently focused, for example, to allow navigation using Tab, Esc and arrow keys.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--tools-and-architecture">

#### Tools and architecture

Focus management lives next to the [user interface element tree](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree) and its architecture is also based on components that respond to user actions within its boundaries and their children. Take a look at a common keyboard navigation scenario in a [classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) instance:

Here are the focus layers that play a role in the navigation and a brief overview of what happens at each layer:

1. The root of the focus tree is the [ClassicEditorUI](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html) class. It creates a [global focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--a-note-about-the-global-focus-tracker) for the entire editor (you can access it via [editor.ui.focusTracker](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#member-focusTracker)).
2. When editing text, you can hit the Alt+F10 keystroke to focus the main editor toolbar, which is the second focus layer.  
  * The [ToolbarView](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) component brings a focus tracker that keeps an eye on its children so that when a user navigates across the toolbar using the keyboard arrows, it is clear which item is focused.
  * Toolbars also use a [focus cycler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class) to provide continuous navigation. For instance, navigating to the next item when the last one is focused brings the focus back to the beginning of the toolbar.
3. When a user selects a toolbar item, its `focus()` method is executed. That brings us to the third layer.  
  * Some components of the toolbar are simple (like [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html)) and their DOM elements are leaves of the focus tree. But some components, for instance, the [DropdownView](../../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html), are containers and allow the focus to go deeper. Each dropdown has a focusable button and can host one child view in its [DropdownPanelView](../../../api/module%5Fui%5Fdropdown%5Fdropdownpanelview-DropdownPanelView.html). It does not need a focus tracker because there are only two ways a user can navigate it: down its panel or away from it.
4. When a user enters the dropdown’s panel, they visit another (fourth) layer of focus. This time it is the [ListView](../../../api/module%5Fui%5Flist%5Flistview-ListView.html) that, like the `ToolbarView`, also needs a focus tracker and a focus cycler to allow smooth keyboard navigation across its items.
5. The outermost leaf of the focus tree in this example is a [ListItemView](../../../api/module%5Fui%5Flist%5Flistitemview-ListItemView.html). It has the [focus()](../../../api/module%5Fui%5Flist%5Flistitemview-ListItemView.html#function-focus) method that focuses its element in the DOM.

And here is the summary of the tools used by each focus layer (UI component):

| Focus layer | Needs [focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class)? | Needs [keystroke handler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class)? | Needs [focus cycler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class)? |   |
| ----------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | - |
| 1           | [ClassicEditorUI](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html)                     | ✅                                                                                                                          | ✅                                                                                                                | ❌ |
| 2           | [ToolbarView](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html)                                   | ✅                                                                                                                          | ✅                                                                                                                | ✅ |
| 3           | [DropdownView](../../../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html)                               | ❌                                                                                                                          | ✅                                                                                                                | ❌ |
| 4           | [ListView](../../../api/module%5Fui%5Flist%5Flistview-ListView.html)                                               | ✅                                                                                                                          | ✅                                                                                                                | ✅ |
| 5           | [ListItemView](../../../api/module%5Fui%5Flist%5Flistitemview-ListItemView.html)                                   | ❌                                                                                                                          | ❌                                                                                                                | ❌ |

Most components have [focus trackers](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class) to keep up with the focus inside of them. Some components that host more children also use [focus cyclers](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class) and [keystroke handlers](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class) to help the user navigate across them. You can learn how to use them in the later sections of this guide:

* [Implementing focusable UI components](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--implementing-focusable-ui-components),
* [Using the FocusTracker class](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class),
* [Using the KeystrokeHandler class](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class),
* [Using the FocusCycler class](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class).

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--implementing-focusable-ui-components">

#### Implementing focusable UI components

Any UI [view](#ckeditor5/latest/framework/architecture/ui-library.html--views) can be focusable. To become one, a view must implement the `focus()` method that focuses the DOM [element](../../../api/module%5Fui%5Fview-View.html#member-element) and the `tabindex="-1"` attribute set on the element that prevents the native navigation using the keyboard (which should be handled by the [focus cycler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class) on the parent–level):

If a view has many focusable children (like a list), the `focus()` method should focus the first child:

Focusable views are what make it possible to navigate the interface of CKEditor using the keyboard. In the [next section](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class), you will learn how parent views keep track of focus among their children using the `FocusTracker` class.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class">

#### Using the `FocusTracker` class

One of the key focus management helpers in the CKEditor 5 UI is the [FocusTracker](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html) class and its instances. They work at the DOM level and offer a fairly simple API:

* Methods to [add()](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html#function-add) and [remove()](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html#function-remove) tracked DOM elements.
* An observable [isFocused](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html#member-isFocused) property telling the world that one of the tracked elements has focus in the DOM.
* An observable [focusedElement](../../../api/module%5Futils%5Ffocustracker-FocusTracker.html#member-focusedElement) property that precisely says which DOM element is focused.

Focus trackers listen to DOM `focus` and `blur` events coming from elements they track and they determine if any is currently focused. As a rule of thumb, a [parent](#ckeditor5/latest/framework/architecture/ui-library.html--view-collections-and-the-ui-tree) to more than one focusable element should have a focus tracker.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--a-note-about-the-global-focus-tracker">

##### A note about the global focus tracker

Each editor instance has a **global focus tracker** that can be accessed via [editor.ui.focusTracker](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#member-focusTracker). It is a special instance that glues all the pieces of the user interface together (including the editing root) and stores the focus state of the **entire editor instance**.

You can **always** listen to the global focus tracker and tell if the user is using the UI:

```
editor.ui.focusTracker.on( 'change:isFocused', ( evt, data, isFocused ) => {
    console.log( `The editor is focused: ${ isFocused }.` );
} );

```

The class responsible for the UI of the editor ([ClassicEditorUI](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html), [InlineEditorUI](../../../api/module%5Feditor-inline%5Finlineeditorui-InlineEditorUI.html), etc.) **must** inform the global focus tracker about the focusable building blocks of the interface, for instance, editable roots of the editor (where the editing takes place) or toolbars.

The same applies to plugins bringing any focusable UI. For instance, the [contextual balloon](../../../api/module%5Fui%5Fpanel%5Fballoon%5Fcontextualballoon-ContextualBalloon.html) plugin that offers a shared floating balloon used by many features across the project (link editing, image tools, widget toolbars, etc.) also registers the balloon in the global focus tracker. Please keep this in mind when developing your custom editor plugins.

The continuity of editor focus is maintained **only** when the global focus tracker is aware of **all** focusable blocks of the UI. Their location in DOM is irrelevant: next to the editable root, in the [“body” collection](../../../api/module%5Fui%5Feditorui%5Fbodycollection-BodyCollection.html) or even somewhere else. To the global focus tracker they are all pieces of the same editor.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--a-practical-example">

##### A practical example

Take a look at the following example of a list that has multiple items, a classic use case for a focus tracker:

To make sure your focus tracker instance and the `items` view collection stay synchronized, create listeners that will update the tracker when a new child view is added or some are removed ([view collections fire events](../../../api/module%5Fui%5Fviewcollection-ViewCollection.html)). The best way to do that is inside the [render()](../../../api/module%5Fui%5Fview-View.html#function-render) method:

```
// Previously imported packages.
// ...

class MyListView extends View {
    constructor( locale ) {
        // More initializations.
        // ...
    }

    // More methods.
    // ...

    render() {
        super.render();

        // Children added before rendering should be known to the #focusTracker.
        for ( const item of this.items ) {
            this.focusTracker.add( item.element );
        }

        // Make sure items added to the collection are recognized by the #focusTracker.
        this.items.on( 'add', ( evt, item ) => {
            this.focusTracker.add( item.element );
        } );

        // Make sure items removed from the collection are ignored by the #focusTracker.
        this.items.on( 'remove', ( evt, item ) => {
            this.focusTracker.remove( item.element );
        } );
    }

    // More methods.
    // ...
}

```

The `MyListView` can now track focused children, and it is time to help the user navigate them using the keyboard. In the next section, you will create a [keystroke handler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class) that will bring you closer to the goal.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class">

#### Using the `KeystrokeHandler` class

The [KeystrokeHandler](../../../api/module%5Futils%5Fkeystrokehandler-KeystrokeHandler.html) helper class allows registering callbacks for the keystrokes. It is used in many views across the UI of the editor for many purposes. For instance, it is responsible for focusing the toolbar on the Alt+F10 key press or it opens the link pop-up form when you hit Ctrl+L on a selected text.

However, in the context of focus management, it is used by the [focus cycler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class) you will get familiar with in the next section. You can learn more about the [KeystrokeHandler](../../../api/module%5Futils%5Fkeystrokehandler-KeystrokeHandler.html) class in the API documentation but for now, you should only know how to create and initialize it before moving forward:

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class">

#### Using the `FocusCycler` class

[FocusCycler](../../../api/module%5Fui%5Ffocuscycler-FocusCycler.html) helps the user navigate the user interface using the keystrokes (arrow keys, Tab, Return, Esc, etc.). This helper class was created with components hosting multiple children in mind, for instance, lists, toolbars or forms. It _cycles_ over their children so, for instance, if the last child is focused and the user wants to move forward, the focus is moved back to the first child. It also supports components that have a variable (dynamic) number of focusable children.

Each focus cycler instance works together with a [focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class) and a [keystroke handler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class). The former delivers the current state of the focus, while the latter helps the cycler integrate with keystrokes, for instance, to focus the next item in the list on the down arrow key press.

Take a look at the example list class using focus cycler, keystroke handler and focus tracker instances together to enable the keyboard navigation. First, all the helpers must be created:

Similarly to the previous sections of this guide, feed the focus tracker and synchronize it with the list items collection in the `render()` method. Since the [MyListView#element](../../../api/module%5Fui%5Fview-View.html#member-element) has already been rendered at that stage, this is also the right moment to start listening to the keyboard events:

```
// Previously imported packages.
// ...

class MyListView extends View {
    constructor( locale ) {
        // More initializations.
        // ...
    }

    render() {
        super.render();

        // Items added before rendering should be known to the #focusTracker.
        for ( const item of this.items ) {
            this.focusTracker.add( item.element );
        }

        // Make sure items added to the collection are recognized by the #focusTracker.
        this.items.on( 'add', ( evt, item ) => {
            this.focusTracker.add( item.element );
        } );

        // Make sure items removed from the collection are ignored by the #focusTracker.
        this.items.on( 'remove', ( evt, item ) => {
            this.focusTracker.remove( item.element );
        } );

        // Start listening for the keystrokes coming from #element, which will allow
        // the #focusCycler to handle the keyboard navigation.
        this.keystrokes.listenTo( this.element );
    }

    focus() {
        if ( this.items.length ) {
            // This will call MyListItemView#focus().
            this.items.first.focus();
        }
    }

    destroy() {
        // Stop listening to all keystrokes when the view is destroyed.
        this.keystrokes.destroy();
    }

    // More methods.
    // ...
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-all-focus-helpers-together">

#### Using all focus helpers together

The complete code of a list class that hosts multiple item views and supports the keyboard navigation across them (when it gets focused) looks as follows:

You can quickly run it in the context of an existing editor in the following way:

```
ClassicEditor
    .create( {
        // The editor's configuration.
        // ...
    } )
    .then( editor => {
        const list = new MyListView( editor.locale );

        // Create two example children.
        const firstChild = new MyListItemView( editor.locale, 'First child' );
        const secondChild = new MyListItemView( editor.locale, 'Second child' );

        // Add children to the list.
        list.items.add( firstChild );
        list.items.add( secondChild );

        // Render the list and put it in the DOM.
        list.render();
        editor.ui.view.body.add( list );

        // Focus the list. This should focus the first child.
        // Use up and down keyboard arrows to cycle across the list items.
        list.focus();
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

Now you can use the keyboard arrows to cycle the focused list items:

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-state-analysis">

### Focus state analysis

This section contains an analysis of a common focus navigation scenario in an [inline editor](#ckeditor5/latest/examples/builds/inline-editor.html). While the [previous section](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--focus-in-the-editor-ui) was focused on tools that make up the focus management system, this time we will focus on their state. This should help you better understand how all little pieces work in a bigger picture.

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--scenario">

#### Scenario

Take a look at the following scenario where both mouse and keyboard are used to navigate the interface of the editor:

And here are the steps of the scenario:

1. The editor is not focused (the focus is somewhere else on the web page).
2. The [editable area](../../../api/module%5Fui%5Feditableui%5Finline%5Finlineeditableuiview-InlineEditableUIView.html) gets focused using the mouse. The main toolbar shows up and because the link was clicked, the [toolbar view](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) also pops up.
3. The Tab key is used to focus the [link preview](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html) in the balloon.
4. The → key is used to focus the [“Edit link” button](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html).
5. The Space key is used to execute the “Edit link” button. The focus moves to the [input](../../../api/module%5Flink%5Fui%5Flinkformview-LinkFormView.html#member-urlInputView) in the [LinkFormView](../../../api/module%5Flink%5Fui%5Flinkformview-LinkFormView.html).
6. The Tab key is used to move from the link URL field to the [“Update” button](../../../api/module%5Flink%5Fui%5Flinkformview-LinkFormView.html#member-saveButtonView).
7. The Tab key is used to move from the “Update” button to the [“Bookmarks” button](#ckeditor5/latest/features/bookmarks.html).
8. The Esc key is used to close the editing form.
9. The Esc key is used to close the link balloon and go back to the editable.

There are 3 focus tracker instances at play in the scenario:

1. The [EditorUI#focusTracker](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#member-focusTracker) (the [“global” focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--a-note-about-the-global-focus-tracker)),
2. The [ToolbarView#focusTracker](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html#member-focusTracker),
3. The [LinkFormView#focusTracker](../../../api/module%5Flink%5Fui%5Flinkformview-LinkFormView.html#member-focusTracker).

Let’s see how they react to the user actions (states were recorded **after** each step):

| Step      | [EditorUI#focusTracker](../../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#member-focusTracker) | [ToolbarView#focusTracker](../../../api/module%5Fui%5Ftoolbar%5Ftoolbarview-ToolbarView.html#member-focusTracker) | [LinkFormView#focusTracker](../../../api/module%5Flink%5Fui%5Flinkformview-LinkFormView.html#member-focusTracker) |             |                |                 |
| --------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | -------------- | --------------- |
| isFocused | focusedElement                                                                                            | isFocused                                                                                                         | focusedElement                                                                                                    | isFocused   | focusedElement |                 |
| 1         | ❌                                                                                                         | null                                                                                                              | ❌                                                                                                                 | null        | ❌              | null            |
| 2         | ✅                                                                                                         | editable                                                                                                          | ❌                                                                                                                 | null        | ❌              | null            |
| 3         | ✅                                                                                                         | balloon panel                                                                                                     | ✅ ✅                                                                                                               | URL preview | ❌              | null            |
| 4         | ✅                                                                                                         | balloon panel                                                                                                     | "Edit link" button                                                                                                | ❌           | null           |                 |
| 5         | ✅                                                                                                         | balloon panel                                                                                                     | ❌                                                                                                                 | null        | ✅              | URL input       |
| 6         | ✅                                                                                                         | balloon panel                                                                                                     | ❌                                                                                                                 | null        | ✅              | "Save" button   |
| 7         | ✅                                                                                                         | balloon panel                                                                                                     | ❌                                                                                                                 | null        | ✅              | "Cancel" button |
| 8         | ✅                                                                                                         | editable                                                                                                          | ❌                                                                                                                 | null        | ❌              | null            |
| 9         | ✅                                                                                                         | editable                                                                                                          | ❌                                                                                                                 | null        | ❌              | null            |

<a id="ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--conclusions">

#### Conclusions

* The [global focus tracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--a-note-about-the-global-focus-tracker) (the one you can access via `editor.ui.focusTracker`) is always aware of the focus state, even when the focus is in the farthest regions of the UI.  
  * It does not know which element is focused on deeper layers (for instance the “Edit link” button), though. All it knows is where the focus went (for example, from the editable to the balloon panel).
  * It lacks precise information about the focus in the link UI because this is the responsibility of the focus tracker of the link UI layer.
  * All editor features **can always depend on the global focus tracker** when necessary. For instance, the main editor toolbar is displayed as long as the global focus tracker knows the focus is somewhere in the editor.
* You can see that the focus management is modular: `ToolbarView` and `LinkFormView` only know about the focus as long as one of their children has it.
* Focus trackers belonging to `ToolbarView` and `LinkFormView` know precisely which element has focus. This is their region of interest and, unlike the global focus tracker of the editor, they need that information to allow navigation using the keyboard.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html">source file: "ckeditor5/latest/framework/deep-dive/ui/localization.html"</a>

## Localization

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--introduction">

### Introduction

All CKEditor 5 WYSIWYG editor features support message localization. It means that the user interface of any feature can be translated into various languages and regions depending on the user’s preferences.

CKEditor 5 translation system is open to third-party plugins. Any custom features that you introduce can be localized. The system also provides a way to add missing or overwrite existing translations and supports translating plural forms.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--open-translation-api">

#### Open translation API

The CKEditor 5 localization system focuses on the following points:

* Supporting the localization of third-party plugins.
* Making it possible to pass your own translations to fix missing or invalid localizations.
* Generating deterministic builds.
* Exposing easy-to-use APIs for providing translations and writing localizable content.
* Supporting plural forms in each step of the localization system for better translations.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--glossary-of-terms">

#### Glossary of terms

Before we start, let us explain the meaning of terms that are crucial for the translation process:

* _A message_ – A string or an object that should be translated.  
The string version works as a shortcut for the `{ id: message, string: message }` object form.
* _A message ID_ – A property used to distinguish messages.  
It is useful for short messages where a collision might occur, like `%0 images`.
* _A message string_ – The default (English) form of the message.  
When the message supports plural versions, this is the default singular version.
* _A message plural_ – An optional plural (English) version of the message.  
The presence of this property indicates that the message should support both singular and plural forms.
* _A PO file (`.po`)_ – A file containing translations for the language in the [PO format](https://www.gnu.org/software/gettext/manual/html%5Fnode/PO-Files.html).  
All localizable packages of CKEditor 5 contain such files in the `lang/translations/` directory.
* _A POT file (`.pot`)_ – A file containing source messages (English sentences) that will be translated.
* _A translation asset_ – A JavaScript file or a part of the file with generated translations for one language.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--writing-a-localizable-ui">

### Writing a localizable UI

All _messages_ that need localization should be passed to the special CKEditor 5’s [t() function](../../../api/module%5Futils%5Flocale-Locale.html#member-t). This function can be retrieved either from the editor’s [Locale](../../../api/module%5Futils%5Flocale-Locale.html) instance: `const { t } = editor.locale;` or from any view method: `const t = this.t;`.

As the first argument, the `t()` function accepts either a string literal or an object literal containing the `id`, `string` and `plural` (optional) properties. The string literal will serve as both the _message ID_ and the _message string_.

As the second argument, the translation function accepts a value or an array of values. These values will be used to fill the placeholders in more advanced translation scenarios. If the `plural` property is specified, the first value will be used as the quantity determining the plural form.

When using the `t()` function, you can create your own _localizable messages_ or reuse _messages_ created in CKEditor 5 packages that your project depends on. In the case of reusing _messages_, you will not need to worry about translating them as all the work will be done by the CKEditor 5 team. Obviously, [your help in translating](#ckeditor5/latest/framework/contributing/contributing.html--translating) will still be appreciated!

For a simple _localizable messages_, use the string form for simplicity:

```
const emojiName = 'cat';

// Assuming that the English language was picked:
t( 'insert emoji' ); // "insert emoji"
t( 'insert %0 emoji', emojiName ); // "insert cat emoji"
t( 'insert %0 emoji', [ emojiName ] ); // "insert cat emoji"

```

For more advanced scenarios, use plain object forms:

```
const quantity = 3;

// Assuming that the English language was picked:
t( { string: '%0 emoji', id: 'ACTION_EMOJI' }, 'insert' ); // "insert emoji"
t( { string: '%0 emoji', plural: '%0 emojis', id: 'N_EMOJIS' }, quantity ); // "3 emojis"
t( { string: '%1 %0 emoji', plural: '%1 %0 emojis', id: 'ACTION_N_EMOJIS' }, [ quantity, 'Insert' ] ); // "Insert 3 emojis"

```

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--example-localizing-the-plugin-ui">

#### Example: Localizing the plugin UI

This example shows how to create a localizable user interface of a plugin. Here is how you can create a button that will insert a smiling face emoji. The button will have a localizable tooltip.

```
// Custom plugin configuration, including necessary imports.
// The code below should be put into a custom plugin class extending the Plugin class.
// ...

editor.ui.componentFactory.add( 'smilingFaceEmoji', locale => {
    const buttonView = new ButtonView( locale );

    // The translation function.
    const { t } = editor.locale;

    // The localized label.
    const label = t( 'Insert smiling face emoji' );

    buttonView.set( {
        label,
        icon: emojiIcon,
        tooltip: true
    } );

    buttonView.on( 'execute', () => {
        editor.execute( 'insertSmilingFaceEmoji' );
        editor.editing.view.focus();
    } );
} );

// The rest of the custom plugin configuration.
// ...

```

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--example-localizing-pending-actions">

#### Example: Localizing pending actions

[Pending actions](../../../api/module%5Fcore%5Fpendingactions-PendingActions.html) are used to inform the user that an action is in progress and they will lose data if they exit the editor at the given moment. Here is how you can localize them:

```
class FileRepository {
    // More methods.
    // ...

    updatePendingAction() {
        const pendingActions = this.editor.plugins.get( PendingActions );

        const t = this.editor.t;
        const getMessage = value => t( 'Upload in progress (%0%).', value ); // Upload in progress (12%).

        this._pendingAction = pendingActions.add( getMessage( this.uploadedPercent ) );
        this._pendingAction.bind( 'message' ).to( this, 'uploadedPercent', getMessage );
    }
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--adding-translations-and-localizing-the-editor-ui">

### Adding translations and localizing the editor UI

First of all, if you found a missing or incorrect translation in any of CKEditor 5 features, [see how you can contribute to the project](#ckeditor5/latest/framework/contributing/contributing.html--translating). CKEditor 5 is an Open Source project used by people from all around the world, so your help will be appreciated by others.

Adding translations to the editor can be done in three ways to satisfy various needs.

* By [adding translations via the translation-service’s add() function](#ckeditor5/latest/framework/deep-dive/ui/localization.html--using-the-add-function).  
This can be done before initiating the CKEditor 5 editor instance but it requires importing the CKEditor 5 utility function.
* By [extending the global window.CKEDITOR\_TRANSLATIONS object](#ckeditor5/latest/framework/deep-dive/ui/localization.html--using-the-windowckeditor%5Ftranslations-object).  
This can be done before initiating the CKEditor 5 editor instance.
* By [creating .po files with translations](#ckeditor5/latest/framework/deep-dive/ui/localization.html--creating-po-files) in the `lang/translations/` directory of the published package like other CKEditor 5 packages do.  
This option will be useful for third-party plugin creators as it allows bundling translations only for needed languages during the webpack compilation step.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--using-the-add-function">

#### Using the `add()` function

The first option for adding translations is via [the translation-service’s add() helper](../../../api/module%5Futils%5Ftranslation-service.html#function-add). This utility adds translations to the global `window.CKEDITOR_TRANSLATIONS` object by extending it. Since it needs to be imported, it works only before building the editor.

Starting with the CKEditor 5 v19.0.0 release, the `add()` method now accepts an optional `getPluralForm()` function as the third argument. This function is only needed for defining the plural form if no language file was loaded for a particular language. It also accepts an array of translations for a _message_ if the _message_ should support singular and plural forms.

```
add( 'pl', {
    'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
} );

// Assuming that the Polish language was picked:
t( { string: 'Add space', plural: 'Add %0 spaces' }, 1 ) // "Dodaj spację"
t( { string: 'Add space', plural: 'Add %0 spaces' }, 2 ) // "Dodaj 2 spacje"
t( { string: 'Add space', plural: 'Add %0 spaces' }, 5 ) // "Dodaj 5 spacji"

```

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--using-the-windowckeditor%5Ftranslations-object">

#### Using the `window.CKEDITOR_TRANSLATIONS` object

The second option is adding translations via the global `window.CKEDITOR_TRANSLATIONS` object.

For each language that should be supported, the `dictionary` property of this object should be extended and the `getPluralForm()` function should be provided if missing.

The `dictionary` property is a `message ID ⇒ translations` map, where the `translations` can be either a string or an array of translations with plural forms for the given language if the message should support plural forms as well.

The `getPluralForm()` property should be a function that returns the plural form index for a given quantity. Note that when using CKEditor 5 translations, this property will be defined by _CKEditor 5 translation assets_.

Check an example below that demonstrates a part of the `window.CKEDITOR_TRANSLATIONS` object with Polish translations for the `Cancel` and `Add space` _message IDs_:

```
{
    // Each key should be a valid language code.
    pl: {
        // A map of translations for the 'pl' language.
        dictionary: {
            'Cancel': 'Anuluj',
            'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
        },

        // A function that returns the plural form index for the given language.
        // Note that you only need to pass this function when you add translations for a new language.
        getPluralForm: n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2
    }
    // Other languages.
    // ...
}

```

It is important to extend the existing properties in the `window.CKEDITOR_TRANSLATIONS` object to not lose other translations. This can be achieved easily using `Object.assign()` and the `||` operator.

```
// Make sure that the global object is defined. If not, define it.
window.CKEDITOR_TRANSLATIONS = window.CKEDITOR_TRANSLATIONS || {};

// Make sure that the dictionary for Polish translations exist.
window.CKEDITOR_TRANSLATIONS[ 'pl' ] = window.CKEDITOR_TRANSLATIONS[ 'pl' ] || {};
window.CKEDITOR_TRANSLATIONS[ 'pl' ].dictionary =  window.CKEDITOR_TRANSLATIONS[ 'pl' ].dictionary || {};

// Extend the dictionary for Polish translations with your translations:
Object.assign( window.CKEDITOR_TRANSLATIONS[ 'pl' ].dictionary, {
    'Save': 'Zapisz'
} );

```

If you add a new language, remember to set the `getPluralForm()` function which should return a number (or a Boolean for languages with simple plural rules like English) that indicates which form should be used for the given value.

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--creating-po-files">

#### Creating `.po` files

The third option of adding plugins should fit mostly owners of plugins that contain many localizable messages. Using this option you need to create a `.po` file per each language code in the `lang/translations/` directory containing translations that follow the [PO file format](https://www.gnu.org/software/gettext/manual/html%5Fnode/PO-Files.html).

```
# lang/translations/es.po

msgid ""
msgstr ""
"Language: es\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "Align left"
msgstr "Alinear a la izquierda"

```

To build and configure a localized editor, follow the steps from the [Setting the UI language guide](#ckeditor5/latest/getting-started/setup/ui-language.html).

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--re-using-translations-from-other-packages">

### Re-using translations from other packages

If you want to re-use a _message_ that already exists in another package, you should use the method `t()` on a `Locale` instance with a changed name instead of [using t() as a function](#ckeditor5/latest/framework/deep-dive/ui/localization.html--writing-a-localizable-ui). This is because using `t()` as a method on the `Locale` is not processed by a static code analyzer. Therefore, it allows to use _messages_ already translated in other packages.

We use this approach already in the [collaboration features](#ckeditor5/latest/features/collaboration/collaboration.html) and the [slash commands feature](#ckeditor5/latest/features/slash-commands.html). You can find an example from the [list of default commands](../../../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandConfig.html#function-getDefaultCommands) that we used in the slash commands feature below. Please note the difference between using `t()` and `translateVariableKey()`. `translateVariableKey( 'Block quote' )` will re-use a translation from another package whilst `t( 'Create a block quote' )` will be processed by a static code analyzer. As a result we make sure that the translation for the `title` is taken from the [block quote](#ckeditor5/latest/features/block-quote.html) feature where the _message_ “Block quote” is already translated. But for the `description` we create a new translation.

```
public getDefaultCommands() {
    const t = this.editor.t;
    const translateVariableKey = this.editor.locale.t;

    return [
        {
            id: 'blockQuote',
            commandName: 'blockQuote',
            icon: IconQuote,
            title: translateVariableKey( 'Block quote' ),
            description: t( 'Create a block quote' )
        },
        // More command definitions
        // ...
    ]
}

```

<a id="ckeditor5/latest/framework/deep-dive/ui/localization.html--known-limitations">

### Known limitations

* Currently it is impossible to change the chosen editor’s language at runtime without destroying the editor.
* Currently it is impossible to add more than one language to the bundle using the CKEditor 5 webpack plugin. In case where multiple _translation assets_ should be added to the application, they should be added using the `<script>` tags or imports to the generated _translation assets_.

<a id="ckeditor5/latest/framework/deep-dive/ui/theme-customization.html">source file: "ckeditor5/latest/framework/deep-dive/ui/theme-customization.html"</a>

## Theme customization

Below you can see a demo of an editor with the dark theme as a result of customizations described later in this guide:

**Mode:**

<a id="ckeditor5/latest/framework/deep-dive/ui/theme-customization.html--theme-mode-light">

Light

<a id="ckeditor5/latest/framework/deep-dive/ui/theme-customization.html--theme-mode-dark">

Dark

<a id="ckeditor5/latest/framework/deep-dive/ui/theme-customization.html--customization-with-css-variables">

### Customization with CSS variables

Assuming you finished our [quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide, and you have a running CKEditor 5 instance, let’s use the full potential of CSS variables (custom properties). The customization explained in this guide will make the theme dark, with slightly bigger text and more rounded corners.

The file containing custom variables can be named `custom.css` and it will look as below:

```
:root {
    /* Helper variables to avoid duplication in the colors. */

    --ck-custom-foreground: hsl(255, 3%, 18%);
    --ck-custom-border: hsl(300, 1%, 22%);
    --ck-custom-white: hsl(0, 0%, 100%);

    /* -- Overrides generic colors. ------------------------------------------------------------- */

    --ck-content-font-color: var(--ck-custom-white);

    --ck-color-base-background: hsl(270, 1%, 29%);
    --ck-color-base-border: hsl(240, 4%, 24%);

    --ck-color-focus-border: hsl(208, 90%, 62%);
    --ck-color-text: hsl(0, 0%, 98%);
    --ck-color-shadow-drop: hsla(0, 0%, 0%, 0.2);
    --ck-color-shadow-inner: hsla(0, 0%, 0%, 0.1);

    /* -- Overrides the default .ck-button class colors. ---------------------------------------- */

    --ck-color-button-default-hover-background: hsl(270, 1%, 22%);
    --ck-color-button-default-active-background: hsl(270, 2%, 20%);
    --ck-color-button-default-active-shadow: hsl(270, 2%, 23%);

    --ck-color-button-on-background: var(--ck-custom-foreground);
    --ck-color-button-on-hover-background: hsl(255, 4%, 16%);
    --ck-color-button-on-active-background: hsl(255, 4%, 14%);
    --ck-color-button-on-active-shadow: hsl(240, 3%, 19%);
    --ck-color-button-on-disabled-background: var(--ck-custom-foreground);

    --ck-color-button-action-background: hsl(168, 76%, 42%);
    --ck-color-button-action-hover-background: hsl(168, 76%, 38%);
    --ck-color-button-action-active-background: hsl(168, 76%, 36%);
    --ck-color-button-action-active-shadow: hsl(168, 75%, 34%);
    --ck-color-button-action-disabled-background: hsl(168, 76%, 42%);
    --ck-color-button-action-text: var(--ck-custom-white);

    --ck-color-button-save: hsl(120, 100%, 46%);
    --ck-color-button-cancel: hsl(15, 100%, 56%);

    /* -- Overrides the default .ck-dropdown class colors. -------------------------------------- */

    --ck-color-dropdown-panel-border: var(--ck-custom-foreground);

    /* -- Overrides the default .ck-dialog class colors. ----------------------------------- */

    --ck-color-dialog-form-header-border: var(--ck-custom-border);

    /* -- Overrides the default .ck-splitbutton class colors. ----------------------------------- */

    --ck-color-split-button-hover-background: var(--ck-color-button-default-hover-background);
    --ck-color-split-button-hover-border: var(--ck-custom-foreground);

    /* -- Overrides the default .ck-input class colors. ----------------------------------------- */

    --ck-color-input-border: hsl(257, 3%, 43%);
    --ck-color-input-text: hsl(0, 0%, 98%);
    --ck-color-input-disabled-background: hsl(255, 4%, 21%);
    --ck-color-input-disabled-border: hsl(250, 3%, 38%);
    --ck-color-input-disabled-text: hsl(0, 0%, 78%);

    /* -- Overrides the default .ck-list class colors. ------------------------------------------ */

    --ck-color-list-button-hover-background: var(--ck-custom-foreground);
    --ck-color-list-button-on-background: hsl(208, 88%, 52%);
    --ck-color-list-button-on-text: var(--ck-custom-white);

    /* -- Overrides the default .ck-balloon-panel class colors. --------------------------------- */

    --ck-color-panel-border: var(--ck-custom-border);

    /* -- Overrides the default .ck-toolbar class colors. --------------------------------------- */

    --ck-color-toolbar-border: var(--ck-custom-border);

    /* -- Overrides the default .ck-tooltip class colors. --------------------------------------- */

    --ck-color-tooltip-background: hsl(252, 7%, 14%);
    --ck-color-tooltip-text: hsl(0, 0%, 93%);

    /* -- Overrides the default colors used by the ckeditor5-image package. --------------------- */

    --ck-content-color-image-caption-background: hsl(0, 0%, 97%);
    --ck-content-color-image-caption-text: hsl(0, 0%, 20%);

    /* -- Overrides the default colors used by the ckeditor5-widget package. -------------------- */

    --ck-color-widget-blurred-border: hsl(0, 0%, 87%);
    --ck-color-widget-hover-border: hsl(43, 100%, 68%);
    --ck-color-widget-editable-focus-background: var(--ck-custom-white);

    /* -- Overrides the default colors used by the ckeditor5-link package. ---------------------- */

    --ck-color-link-default: hsl(190, 100%, 75%);
}

/* Improve displaying links. */
.ck.ck-editor__editable a {
    color: hsl(210, 100%, 63%);
}

/* Improve displaying code blocks. */
.ck-content pre {
    color: hsl(0, 0%, 91%);
    border-color: hsl(0, 0%, 77%);
}

```

Depending on your setup method, you can either import a style sheet into your `js` file:

```
import { ClassicEditor } from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

// Override the default styles.
import 'custom.css';

ClassicEditor
    .create( /* ... */ )
    .then( editor => {
        console.log( editor );
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

Or import it via the `link` in `html` in the CDN setup:

```
<link rel="stylesheet" href="path/to/custom.css" type="text/css">

```

<a id="ckeditor5/latest/framework/deep-dive/ui/widget-internals.html">source file: "ckeditor5/latest/framework/deep-dive/ui/widget-internals.html"</a>

## Deep dive into widget internals

<a id="ckeditor5/latest/framework/deep-dive/ui/widget-internals.html--disabling-the-widget-type-around-feature">

### Disabling the widget type around feature

The [WidgetTypeAround](../../../api/module%5Fwidget%5Fwidgettypearound%5Fwidgettypearound-WidgetTypeAround.html) plugin allows users to type around the widgets, in places where it is normally impossible to place the caret due to limitations of the web browsers. Although this feature boosts productivity and ease of typing, some integrations may not want or need it, for instance:

* When the UI of the feature collides with the integration.
* When typing outside widgets should be impossible (content made exclusively of widgets).
* When certain widgets have a fixed location in the document that should never change.

In the sections that follow, you will learn how to configure CKEditor 5 WYSIWYG editor to address these specific needs.

<a id="ckeditor5/latest/framework/deep-dive/ui/widget-internals.html--hiding-the-buttons-that-insert-paragraphs-around-widgets">

#### Hiding the buttons that insert paragraphs around widgets

The easiest way to get rid of the type-around widget buttons is to hide them using CSS. Put the following code snippet anywhere in your application and the buttons will no longer be displayed:

```
.ck.ck-editor__editable .ck-widget .ck-widget__type-around__button {
    display: none;
}

```

If you only want to customize the type around widget buttons, you can use the same CSS selector to modify their look or position.

<a id="ckeditor5/latest/framework/deep-dive/ui/widget-internals.html--disabling-the-entire-feature">

#### Disabling the entire feature

Although the [WidgetTypeAround](../../../api/module%5Fwidget%5Fwidgettypearound%5Fwidgettypearound-WidgetTypeAround.html) plugin is an integral part of the [widget](../../../api/module%5Fwidget%5Fwidget-Widget.html) subsystem and is loaded by default whenever an editor feature uses widgets (for instance, for [images](#ckeditor5/latest/features/images/images-overview.html) or [tables](#ckeditor5/latest/features/tables/tables.html)), you can still disable it on the fly. Turning off the feature will both hide the widget buttons and disable other behaviors, for instance:

* The caret will not be rendered before or after a widget when the user navigates the document using arrow keys.
* The Enter and Shift+Enter keystrokes will no longer insert paragraphs if pressed when a widget is selected.

Use the [forceDisabled()](../../../api/module%5Fcore%5Fplugin-Plugin.html#function-forceDisabled) method of the plugin to disable it on the fly like in the snippet below:

```
ClassicEditor
    .create( {
        // The editor's configuration.
        // ...
    } )
    .then( editor => {
        const widgetTypeAroundPlugin = editor.plugins.get( 'WidgetTypeAround' );

        // Disable the widget type around plugin.
        widgetTypeAroundPlugin.forceDisabled( 'MyApplication' );
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

You can always re–enable the plugin using the following snippet

```
widgetTypeAroundPlugin.clearForceDisabled( 'MyApplication' );

```

Refer to the [API documentation](../../../api/module%5Fcore%5Fplugin-Plugin.html#function-clearForceDisabled) to learn more.

<a id="ckeditor5/latest/framework/deep-dive/ui/widget-internals.html--exclude-dom-events-from-default-handlers">

### Exclude DOM events from default handlers

Sometimes it can be useful to prevent processing of events by default handlers, for example using React component inside an `UIElement` in the widget where, by default, widget itself wants to control everything. To make it possible the only thing to do is to add a `data-cke-ignore-events` attribute to an element or to its ancestor and then all events triggered by any of children from that element will be ignored in default handlers.

Let’s see it in an short example:

```
<div data-cke-ignore-events="true">
    <button>Click!</button>
</div>

```

In the above template events dispatched from the button, which is placed inside `<div>` containing `data-cke-ignore-events` attribute, will be ignored by default event handlers.

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html">source file: "ckeditor5/latest/framework/deep-dive/upload-adapter.html"</a>

## Custom image upload adapter

In this guide, you will learn the basic concepts of the file upload architecture in CKEditor 5 WYSIWYG editor which will help you implement your custom upload adapter.

While this guide is mainly focused on image upload (the most common kind of upload), the presented concepts and the API allow development of all sorts of file upload adapters for different file types like PDF files, movies, etc.

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--glossary-of-terms">

### Glossary of terms

Before you start, make sure all terms used in this guide are clear.

| Term                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Upload adapter                                                                           | A piece of code (a class) that handles the image upload from the moment it is requested by the user (for example, when the file is dropped into the content) to the moment the server returns a response to the requested upload. A bridge between the feature and the server. Upload adapters are used by other plugins like [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) to connect to the server and fetch the response. For every user action (for example, when a file is dropped into the content), a new upload adapter instance is created. CKEditor 5 comes with some [official upload adapters](#ckeditor5/latest/features/images/image-upload/image-upload.html--official-upload-adapters) but you can also [implement your own adapters](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--implementing-a-custom-upload-adapter). See the ["How does the image upload work?"](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--how-does-the-image-upload-work) section to learn more. |
| [UploadAdapter](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html) interface | An interface defining the minimal API required to create an upload adapter. In other words, it tells you what methods your upload adapter class must have to work. See ["The anatomy of the adapter"](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--the-anatomy-of-the-adapter) section to learn more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [File repository](../../api/module%5Fupload%5Ffilerepository-FileRepository.html) plugin | A central point for managing file upload in CKEditor 5\. It glues upload adapters and features using them: Upload adapters are enabled in the editor by defining the [FileRepository.createUploadAdapter()](../../api/module%5Fupload%5Ffilerepository-FileRepository.html#member-createUploadAdapter) factory method. Features like [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) use the FileRepository API to create a new upload adapter instance each time an upload is requested by the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [Image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin           | A top-level plugin that responds to actions of the users (for example, when a file is dropped into the content) by uploading files to the server and updating the edited content once the upload finishes. This particular plugin handles user actions related to uploading images. It uses the FileRepository API to spawn upload adapter instances, triggers the image upload (UploadAdapter.upload()), and uses the data returned by the adapter's upload promise to update the image in the editor content. See the ["How does the image upload work?"](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--how-does-the-image-upload-work) section to learn more.                                                                                                                                                                                                                                                                                                                                                                   |

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--how-does-the-image-upload-work">

### How does the image upload work?

Before you can create your custom upload adapter, you should learn about the image upload process in CKEditor 5\. The whole process consists of the following steps:

1. First, an image (or images) needs to get into the rich-text editor content. There are many ways to do that, for instance:

  * pasting an image from the clipboard,
  * dragging a file from the file system,
  * selecting an image through a file system dialog.  
The images are intercepted by the [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin.
2. For every image, the image upload plugin [creates an instance of a file loader](../../api/module%5Fupload%5Ffilerepository-FileRepository.html#function-createLoader).

  * The role of the **file loader** is to read the file from the disk and upload it to the server by using the upload adapter.
  * The role of the **upload adapter** is, therefore, to securely send the file to the server and pass the response from the server (for example, the URL to the saved file) back to the file loader (or handle an error, if there was one).
3. While the images are being uploaded, the image upload plugin:

  * Creates placeholders for these images.
  * Inserts them into the editor.
  * Displays the progress bar for each of them.
  * When an image is deleted from the editor content before the upload finishes, it aborts the upload process.
4. Once the file is uploaded, the upload adapter notifies the editor about this fact by resolving its `Promise`. It passes the URL (or URLs in case of responsive images) to the image upload plugin which replaces the `src` and `srcset` attributes of the image placeholder in the editor content.

This is just an overview of the image upload process. Actually, the whole thing is more complicated. For instance, images can be copied and pasted within the WYSIWYG editor (while the upload takes place) and all potential upload errors must be handled, too. The good news is these tasks are handled transparently by the [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin so you do not have to worry about them.

To sum up, for the image upload to work in the rich-text editor, two conditions must be true:

* **The [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin must be enabled** in the editor.
* **The upload adapter needs to be defined**. This can be done by using (enabling _and_ configuring):

  * [One of the existing upload adapters](#ckeditor5/latest/features/images/image-upload/image-upload.html--official-upload-adapters).
  * [Your custom upload adapter](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--implementing-a-custom-upload-adapter) and handling uploaded files on your server backend.

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--the-anatomy-of-the-adapter">

### The anatomy of the adapter

A custom upload adapter allows you to take **full control** over the process of sending the files to the server as well as passing the response from the server back to the rich-text editor.

Any upload adapter, whether an image upload adapter or a generic file upload adapter, must implement the [UploadAdapter interface](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html) to work, that is, it must bring its own `upload()` and `abort()` methods.

* The [upload()](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html#function-upload) method must return a promise:  
  * **resolved** by a successful upload with an object containing information about the uploaded file (see the section about [responsive images](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--responsive-images-and-srcset-attribute) to learn more),
  * **rejected** because of an error, in which case nothing is inserted into the content.
* The [abort()](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html#function-abort) method must allow the editor to stop the upload process. It is necessary, for instance, when the image was removed from the content by the user before the upload finished or the editor instance was [destroyed](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-destroy).

In its simplest form, a custom adapter implementing the `UploadAdapter` interface will look as follows. Note that `server.upload()`, `server.onUploadProgress()` and `server.abortUpload()` should be replaced by specific implementations (dedicated for your application) and only demonstrate the minimal communication necessary for the upload to work:

```
class MyUploadAdapter {
    constructor( loader ) {
        // The file loader instance to use during the upload.
        this.loader = loader;
    }

    // Starts the upload process.
    upload() {
        // Update the loader's progress.
        server.onUploadProgress( data => {
            loader.uploadTotal = data.total;
            loader.uploaded = data.uploaded;
        } );

        // Return a promise that will be resolved when the file is uploaded.
        return loader.file
            .then( file => server.upload( file ) );
    }

    // Aborts the upload process.
    abort() {
        // Reject the promise returned from the upload() method.
        server.abortUpload();
    }
}

```

Define the [FileRepository.createUploadAdapter()](../../api/module%5Fupload%5Ffilerepository-FileRepository.html#member-createUploadAdapter) factory method which uses the `MyUploadAdapter` class to enable the upload adapter in the editor:

```
editor.plugins.get( 'FileRepository' ).createUploadAdapter = ( loader ) => {
    return new MyUploadAdapter( loader );
};

```

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--implementing-a-custom-upload-adapter">

### Implementing a custom upload adapter

In this section, you are going to implement and enable a custom upload adapter. The adapter will use the native [XMLHttpRequest](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) to send files returned by the loader to a pre–configured URL on the server, handling the `error`, `abort`, `load`, and `progress` events fired by the request.

To start off, define the `MyUploadAdapter` class with its constructor.

```
class MyUploadAdapter {
    constructor( loader ) {
        // The file loader instance to use during the upload. It sounds scary but do not
        // worry — the loader will be passed into the adapter later on in this guide.
        this.loader = loader;
    }

    // More methods.
    // ...
}

```

Implement the minimal `UploadAdapter` adapter interface as explained in [“The anatomy of the adapter”](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--the-anatomy-of-the-adapter) section. The details of the implementation are explained in the following chapters of this guide.

```
class MyUploadAdapter {
    // The constructor method.
    // ...

    // Starts the upload process.
    upload() {
        return this.loader.file
            .then( file => new Promise( ( resolve, reject ) => {
                this._initRequest();
                this._initListeners( resolve, reject, file );
                this._sendRequest( file );
            } ) );
    }

    // Aborts the upload process.
    abort() {
        if ( this.xhr ) {
            this.xhr.abort();
        }
    }

    // More methods.
    // ...
}

```

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--using-xmlhttprequest-in-an-adapter">

#### Using `XMLHttpRequest` in an adapter

Let’s see what the `_initRequest()` method looks like in your custom upload adapter. It should prepare the `XMLHttpRequest` object before it can be used to upload an image.

```
class MyUploadAdapter {
    // More methods.
    // ...

    // Initializes the XMLHttpRequest object using the URL passed to the constructor.
    _initRequest() {
        const xhr = this.xhr = new XMLHttpRequest();

        // Note that your request may look different. It is up to you and your editor
        // integration to choose the right communication channel. This example uses
        // a POST request with JSON as a data structure but your configuration
        // could be different.
        xhr.open( 'POST', 'http://example.com/image/upload/path', true );
        xhr.responseType = 'json';
    }
}

```

Now focus on the `_initListeners()` method which attaches the `error`, `abort`, `load`, and `progress` event listeners to the `XMLHttpRequest` object created in the last step.

A successful image upload will finish when the upload promise is resolved upon the `load` event fired by the `XMLHttpRequest` request. The promise must be resolved with an object containing information about the image. See the documentation of the [upload()](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html#function-upload) method to learn more.

```
class MyUploadAdapter {
    // More methods.
    // ...

    // Initializes XMLHttpRequest listeners.
    _initListeners( resolve, reject, file ) {
        const xhr = this.xhr;
        const loader = this.loader;
        const genericErrorText = `Couldn't upload file: ${ file.name }.`;

        xhr.addEventListener( 'error', () => reject( genericErrorText ) );
        xhr.addEventListener( 'abort', () => reject() );
        xhr.addEventListener( 'load', () => {
            const response = xhr.response;

            // This example assumes the XHR server's "response" object will come with
            // an "error" which has its own "message" that can be passed to reject()
            // in the upload promise.
            //
            // Your integration may handle upload errors in a different way so make sure
            // it is done properly. The reject() function must be called when the upload fails.
            if ( !response || response.error ) {
                return reject( response && response.error ? response.error.message : genericErrorText );
            }

            // If the upload is successful, resolve the upload promise with an object containing
            // at least the "default" URL, pointing to the image on the server.
            // This URL will be used to display the image in the content. Learn more in the
            // UploadAdapter#upload documentation.
            resolve( {
                default: response.url
            } );
        } );

        // Upload progress when it is supported. The file loader has the #uploadTotal and #uploaded
        // properties which are used e.g. to display the upload progress bar in the editor
        // user interface.
        if ( xhr.upload ) {
            xhr.upload.addEventListener( 'progress', evt => {
                if ( evt.lengthComputable ) {
                    loader.uploadTotal = evt.total;
                    loader.uploaded = evt.loaded;
                }
            } );
        }
    }
}

```

Finally, the `_sendRequest()` method sends the `XMLHttpRequest`. In this example, the [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) interface is used to pass the file provided by the [file loader](../../api/module%5Fupload%5Ffilerepository-FileRepository.html#function-createLoader).

```
class MyUploadAdapter {
    // More methods.
    // ...

    // Prepares the data and sends the request.
    _sendRequest( file ) {
        // Prepare the form data.
        const data = new FormData();

        data.append( 'upload', file );

        // Important note: This is the right place to implement security mechanisms
        // like authentication and CSRF protection. For instance, you can use
        // XMLHttpRequest.setRequestHeader() to set the request headers containing
        // the CSRF token generated earlier by your application.

        // Send the request.
        this.xhr.send( data );
    }
}

```

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--responsive-images-and-srcset-attribute">

#### Responsive images and `srcset` attribute

If the upload is successful, a `Promise` returned by the [MyUploadAdapter.upload()](../../api/module%5Fupload%5Ffilerepository-UploadAdapter.html#function-upload) method can resolve with more than just a `default` path to the uploaded image. See the implementation of `MyUploadAdapter._initListeners()`. This usually looks like this:

```
{
    default: 'http://example.com/images/image–default-size.png'
}

```

Other image sizes can also be provided in the response, allowing [responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia%5Fand%5Fembedding/Responsive%5Fimages) in the editor. The response containing more than just one image size could look like this:

```
{
    default: 'http://example.com/images/image–default-size.png',
    '160': 'http://example.com/images/image–size-160.image.png',
    '500': 'http://example.com/images/image–size-500.image.png',
    '1000': 'http://example.com/images/image–size-1000.image.png',
    '1052': 'http://example.com/images/image–default-size.png'
}

```

The [image upload](../../api/module%5Fimage%5Fimageupload-ImageUpload.html) plugin is capable of handling multiple image sizes returned by the upload adapter. It will automatically add the URLs to other images sizes to the `srcset` attribute of the image in the content.

Knowing that, you can implement the `XMLHttpRequest#load` listener that resolves the upload promise in the [previous section](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--using-xmlhttprequest-in-an-adapter) so that it passes the entire `urls` property of the server response to the image upload plugin:

```
// The rest of the MyUploadAdapter class definition.
// ...

xhr.addEventListener( 'load', () => {
    const response = xhr.response;

    // Response handling.
    // ...

    // response.urls = {
    // 	default: 'http://example.com/images/image–default-size.png',
    // 	'160': '...',
    // 	'500': '...',
    // 	More response urls.
    //  ...
    // 	'1052': 'http://example.com/images/image–default-size.png'
    // }
    resolve( response.urls );
} );

// The rest of the MyUploadAdapter class definition.
// ...

```

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--passing-additional-data-to-the-response">

#### Passing additional data to the response

There is a chance you might need to pass some data from the server to provide additional data to some features. To do that, you need to wrap all URLs in the `urls` property and pass additional data in the top level of the object.

For image uploading, you can later retrieve the data in the [uploadComplete](../../api/module%5Fimage%5Fimageupload%5Fimageuploadediting-ImageUploadEditing.html#event-uploadComplete) event. This allows setting new attributes and overriding the existing ones on the model image based on the data just after the image is uploaded.

```
{
    urls: {
        default: 'http://example.com/images/image–default-size.png',
        // Optional different sizes of images.
    },
    customProperty: 'foo'
}

```

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--activating-a-custom-upload-adapter">

#### Activating a custom upload adapter

Having implemented the adapter, you must figure out how to enable it in the WYSIWYG editor. The good news is that it is pretty easy, and you do not need to rebuild the editor to do that!

You are going to extend the basic implementation presented in [“The anatomy of the adapter”](#ckeditor5/latest/framework/deep-dive/upload-adapter.html--the-anatomy-of-the-adapter) section of this guide so your custom adapter becomes an editor plugin. To do that, create a simple standalone plugin (`MyCustomUploadAdapterPlugin`) that will [create an instance of the file loader](../../api/module%5Fupload%5Ffilerepository-FileRepository.html#function-createLoader) and glue it with your custom `MyUploadAdapter`.

Enable the `MyCustomUploadAdapterPlugin` in the editor by using the [config.extraPlugins](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-extraPlugins) option:

```
ClassicEditor
    .create( {
        plugins: [ MyCustomUploadAdapterPlugin, Essentials, Paragraph, Image, ImageUpload, /* ... */ ],
        // More configuration options.
        // ...
    } )
    .catch( error => {
        console.log( error );
    } );

```

Run the editor and see if your implementation works. Drop an image into the WYSIWYG editor content and it should be uploaded to the server thanks to the `MyUploadAdapter`.

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--the-complete-implementation">

#### The complete implementation

Here is what the complete implementation of an `XMLHttpRequest`–based upload adapter looks like. You can use this code as a foundation to build custom upload adapters for your applications.

<a id="ckeditor5/latest/framework/deep-dive/upload-adapter.html--whats-next">

### What’s next

Check out the comprehensive [image upload overview](#ckeditor5/latest/features/images/image-upload/image-upload.html) guide to learn more about different ways of uploading images in CKEditor 5\. See the [image feature](#ckeditor5/latest/features/images/images-overview.html) guide to find out more about handling images in CKEditor 5.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html">source file: "ckeditor5/latest/framework/develpment-tools/inspector.html"</a>

## CKEditor 5 inspector

The official [CKEditor 5 inspector](https://github.com/ckeditor/ckeditor5-inspector) provides a set of rich debugging tools for editor internals like [model](#ckeditor5/latest/framework/architecture/editing-engine.html--model), [view](#ckeditor5/latest/framework/architecture/editing-engine.html--view), and [commands](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands).

It allows you to observe changes to the data structures and the selection live in the editor, which is particularly helpful when developing new rich-text editor features or getting to understand the existing ones.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--importing-the-inspector">

### Importing the inspector

You can import the inspector as an [@ckeditor/ckeditor5-inspector](https://www.npmjs.com/package/@ckeditor/ckeditor5-inspector) package into your project:

```
npm install --save-dev @ckeditor/ckeditor5-inspector

```

and then either import it as a module:

```
import CKEditorInspector from '@ckeditor/ckeditor5-inspector';

```

or as a plain `<script>` tag in the HTML of your application:

```
<script src="../node_modules/@ckeditor/ckeditor5-inspector/build/inspector.js"></script>

```

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--inspector-as-a-bookmarklet">

### Inspector as a bookmarklet

If you do not wish to import the inspector, you can create a bookmarklet in your browser instead that will allow you to open it on any page without interference with its source code.

**Important note: this method will not work if the page has the Content Security Policy enabled.**

To create such a bookmarklet, paste the following code as the URL of a new bookmark in the browser of your choice:

```
javascript:(function(){let script=document.createElement('script');script.src='https://unpkg.com/@ckeditor/ckeditor5-inspector/build/inspector.js';script.onload=()=>CKEditorInspector.attachToAll();document.head.appendChild(script);})()

```

Now you can load CKEditor 5 inspector by using the newly created bookmark.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--enabling-the-inspector">

### Enabling the inspector

Attach the inspector to the editor instance when [created](#ckeditor5/latest/getting-started/setup/editor-lifecycle.html--creating-an-editor-with-create) using the `CKEditorInspector.attach()` method:

```
ClassicEditor
    .create( /* ... */ )
    .then( editor => {
        CKEditorInspector.attach( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

```

The inspector will show up at the bottom of the screen.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--inspecting-multiple-editors">

### Inspecting multiple editors

You can inspect multiple CKEditor 5 instances at a time by calling `CKEditorInspector.attach()` for each one of them. Then you can switch the inspector context to inspect different editor instances.

You can specify the name of the editor when attaching to make working with multiple instances easier:

```
// Inspecting two editor instances at the same time.
CKEditorInspector.attach( { 'header-editor': editor } );
CKEditorInspector.attach( { 'body-editor': editor } );

```

The editor switcher is in the upper–right corner of the inspector panel.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--demo">

#### Demo

Click the **“Inspect editor”** button below to attach the inspector to the editor:

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--compatibility">

#### Compatibility

The inspector works with CKEditor 5 [v12.0.0](https://github.com/ckeditor/ckeditor5/releases/tag/v12.0.0)+.

<a id="ckeditor5/latest/framework/develpment-tools/inspector.html--contributing-to-the-inspector">

#### Contributing to the inspector

The source code of CKEditor 5 inspector and its issue tracker is available on GitHub in <https://github.com/ckeditor/ckeditor5-inspector>.

<a id="ckeditor5/latest/framework/develpment-tools/mrgit.html">source file: "ckeditor5/latest/framework/develpment-tools/mrgit.html"</a>

## Mr. Git

[Mr. Git](https://github.com/cksource/mrgit) is a multi-repository manager for Git. In CKEditor 5, you can use it for easy development and testing of various CKEditor 5-related repositories, such as [ckeditor5-dev](https://github.com/ckeditor/ckeditor5-dev) or [ckeditor5-linters-config](https://github.com/ckeditor/ckeditor5-linters-config).

<a id="ckeditor5/latest/framework/develpment-tools/mrgit.html--setup">

### Setup

To use the tool, install it globally from the npm.

```
npm install -g mrgit

```

Then, put a file named `mrgit.json` in the root of the `ckeditor5` repository. This is an example content of this file:

```
{
    "packages": "external/",
    "dependencies": {
        "ckeditor5-linters-config": "ckeditor/ckeditor5-linters-config@latest",
        "ckeditor5-dev": "ckeditor/ckeditor5-dev@latest"
    },
    "presets": {
        "dev": {
            "ckeditor5-dev": "ckeditor/ckeditor5-dev"
        },
        "example-feature": {
            "ckeditor5-linters-config": "ckeditor/ckeditor5-linters-config#i/1-example-feature",
            "ckeditor5-dev": "ckeditor/ckeditor5-dev#i/1-example-feature"
        }
    }
}

```

<a id="ckeditor5/latest/framework/develpment-tools/mrgit.html--usage">

### Usage

In the example configuration file listed above, we have defined base dependencies that should be used. These use the `@latest` tag, which means that the latest release tag will be used. This should coincide with the latest version available on npm. After calling `mrgit sync`, these dependencies will be cloned and made available locally in the specified (latest) version.

Alternatively, you can use one of the presets defined in the latter section of the file, for example, the `dev` preset. To do so, execute `mrgit sync --preset dev` – this will use versions specified in the preset instead. `ckeditor/ckeditor5-dev` does not have any tag or branch specified, so the `master` branch will be used by default.

Since only `ckeditor5-dev` is specified in this preset, version used for `ckeditor5-linters-config` will be the same as specified in the default `dependencies` section. Using this mechanism, it is possible to switch between production and development versions of the dependencies used by the `ckeditor5` repository.

For all available commands and configuration options, see the [Mr. Git documentation](https://github.com/cksource/mrgit#mr-git).

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html">source file: "ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html"</a>

## Understand the generated build output

Running `npm run build` creates two flavors of output in `dist/`: one for npm-based installations and one for direct browser loading. You can use the same generated package together with the standard CKEditor 5 npm, ZIP, or CDN distributions.

This guide uses `<packageName>` as the npm package placeholder. `Callout` and `CKCallout` are example plugin and UMD global names for `ckeditor5-callout`. Your actual package, plugin, and global names depend on the values you used during generation.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--generated-project-structure">

### Generated project structure

The generated package has a small, predictable structure:

| Path                                           | Purpose                                                |
| ---------------------------------------------- | ------------------------------------------------------ |
| src/                                           | Plugin source files and the package entry point.       |
| sample/                                        | The local sample app loaded by npm run start.          |
| tests/                                         | Unit tests run by Vitest.                              |
| theme/                                         | Icons and CSS used by your plugin.                     |
| lang/                                          | Translation context and generated \*.po files.         |
| scripts/                                       | Helper scripts, including translation synchronization. |
| dist/                                          | Files created by npm run build.                        |
| ckeditor5-metadata.json                        | Plugin metadata used by CKEditor 5 tools.              |
| vite.config.\[js\|ts\]                         | Build and test configuration.                          |
| src/augmentation.ts, typings/, tsconfig\*.json | TypeScript-only typing support.                        |

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--typescript-augmentation">

### TypeScript augmentation

When you choose the TypeScript template, the generator creates the `src/augmentation.ts` file. This is the place where the generated package augments CKEditor 5 types such as `PluginsMap`. Update this file when you add new plugins or commands.

Depending on your plugin, you will usually augment one or more of these interfaces:

* [EditorConfig](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) when your plugin adds configuration.
* [PluginsMap](../../../api/module%5Fcore%5Fplugincollection-PluginsMap.html) when you want `editor.plugins.get()` to return your plugin type.
* [CommandsMap](../../../api/module%5Fcore%5Fcommandcollection-CommandsMap.html) when you add commands and want `editor.commands.get()` to return typed results.

The generated template already imports `./augmentation.js` from `src/index.ts`.

```
import type { Callout } from './index.js';

declare module '@ckeditor/ckeditor5-core' {
    interface PluginsMap {
        [ Callout.pluginName ]: Callout;
    }
}

```

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--what-goes-into-dist">

### What goes into `dist/`

After `npm run build`, the output looks similar to this:

```
dist/
├─ index.js
├─ index.css
├─ index.d.ts                # TypeScript only
├─ callout.d.ts              # TypeScript only
├─ augmentation.d.ts         # TypeScript only, if present
└─ browser/
    ├─ index.es.js
    ├─ index.umd.js
    └─ index.css

```

Each file has a different job:

| File                      | Use it for                                                                                                                                      |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| dist/index.js             | The npm package entry. It is ESM and keeps ckeditor5 as an external dependency.                                                                 |
| dist/index.css            | The CSS file for npm consumers. Import it separately in the consuming app.                                                                      |
| dist/\*.d.ts              | TypeScript declarations generated from src/. They are published together with the npm build.                                                    |
| dist/browser/index.es.js  | The browser ESM build for type="module" and import-map setups. It still expects ckeditor5 to be provided separately.                            |
| dist/browser/index.umd.js | The browser UMD build for plain <script> setups. It expects CKEDITOR to exist and exposes your package on the global name chosen for the build. |
| dist/browser/index.css    | The CSS file for ZIP and CDN-style browser integrations.                                                                                        |

`package.json` is already configured so that publishing the package ships `dist/` and `ckeditor5-metadata.json`.

What you do not get from the generator:

* No full editor bundle with CKEditor 5 built in.
* No ZIP archive ready to download.
* No automatic CDN hosting.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--use-the-output-with-npm">

### Use the output with npm

Start from the [npm or ZIP quick start](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html) guide, then add your generated package on top.

The npm build is the right choice when your application already uses a package manager and a bundler. Publish the package to npm, install it from a local path, or use it from a workspace. In every case, the consuming project loads the package root, not `dist/browser/`.

```
npm install ckeditor5 <packageName>

```

```
import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
import { Callout } from '<packageName>';

import 'ckeditor5/ckeditor5.css';
import '<packageName>/index.css';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        root: {
            initialData: '<p>Hello from CKEditor 5!</p>'
        },
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Essentials, Paragraph, Callout ],
        toolbar: [ 'undo', 'redo', '|', 'callout' ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

TypeScript consumers automatically pick up the generated declaration files through the package `types` entry.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--use-the-output-with-a-zip-based-setup">

### Use the output with a ZIP-based setup

Start from the [npm or ZIP quick start](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html) guide, then copy `dist/browser/` to the same static assets area where you keep the extracted CKEditor 5 ZIP files.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--recommended-esm-with-import-maps">

#### Recommended: ESM with import maps

Use `dist/browser/index.es.js` when your page loads CKEditor 5 from ESM files and import maps:

```
<div id="editor"></div>

<link rel="stylesheet" href="./vendor/ckeditor5/ckeditor5.css" />
<link rel="stylesheet" href="./vendor/callout/index.css" />

<script type="importmap">
    {
        "imports": {
            "ckeditor5": "./vendor/ckeditor5/ckeditor5.js",
            "ckeditor5/": "./vendor/ckeditor5/",
            "<packageName>": "./vendor/callout/index.es.js"
        }
    }
</script>

<script type="module">
    import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
    import { Callout } from '<packageName>';

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            root: {
                initialData: '<p>Hello from CKEditor 5!</p>'
            },
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Paragraph, Callout ],
            toolbar: [ 'undo', 'redo', '|', 'callout' ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--alternative-umd-with-script-tags">

#### Alternative: UMD with script tags

Use `dist/browser/index.umd.js` when your page uses the UMD files from the ZIP package:

```
<div id="editor"></div>

<link rel="stylesheet" href="./vendor/ckeditor5/ckeditor5.css" />
<link rel="stylesheet" href="./vendor/callout/index.css" />

<script src="./vendor/ckeditor5/ckeditor5.umd.js"></script>
<script src="./vendor/callout/index.umd.js"></script>

<script>
    const { ClassicEditor, Essentials, Paragraph } = CKEDITOR;
    const { Callout } = CKCallout;

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            root: {
                initialData: '<p>Hello from CKEditor 5!</p>'
            },
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Paragraph, Callout ],
            toolbar: [ 'undo', 'redo', '|', 'callout' ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

`CKCallout` is the example UMD global. If your package is `ckeditor5-callout`, this is the suggested default name. Otherwise, replace it with the global name you confirmed during generation.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--use-the-output-with-cdn-or-cloud-setups">

### Use the output with CDN or cloud setups

Start from the [CDN quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide, then host your generated browser files yourself. CKEditor 5 can come from the CDN, while your plugin still comes from your server.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--recommended-import-maps">

#### Recommended: import maps

```
<div id="editor"></div>

<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
<link rel="stylesheet" href="/plugins/callout/index.css" />

<script type="importmap">
    {
        "imports": {
            "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
            "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",
            "<packageName>": "/plugins/callout/index.es.js"
        }
    }
</script>

<script type="module">
    import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';
    import { Callout } from '<packageName>';

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            root: {
                initialData: '<p>Hello from CKEditor 5!</p>'
            },
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Paragraph, Callout ],
            toolbar: [ 'undo', 'redo', '|', 'callout' ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--alternative-umd-globals">

#### Alternative: UMD globals

```
<div id="editor"></div>

<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
<link rel="stylesheet" href="/plugins/callout/index.css" />

<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
<script src="/plugins/callout/index.umd.js"></script>

<script>
    const { ClassicEditor, Essentials, Paragraph } = CKEDITOR;
    const { Callout } = CKCallout;

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            root: {
                initialData: '<p>Hello from CKEditor 5!</p>'
            },
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Paragraph, Callout ],
            toolbar: [ 'undo', 'redo', '|', 'callout' ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html--choose-the-right-output-quickly">

### Choose the right output quickly

| If your project uses…                       | Use these generated files                                                          |
| ------------------------------------------- | ---------------------------------------------------------------------------------- |
| npm and a bundler                           | dist/index.js and dist/index.css                                                   |
| ZIP files and import maps                   | dist/browser/index.es.js and dist/browser/index.css                                |
| ZIP files and plain <script> tags           | dist/browser/index.umd.js and dist/browser/index.css                               |
| CKEditor Cloud CDN plus your static hosting | dist/browser/index.es.js or dist/browser/index.umd.js, plus dist/browser/index.css |

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html">source file: "ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html"</a>

## Create a CKEditor 5 package with package generator

The [ckeditor5-package-generator](https://www.npmjs.com/package/ckeditor5-package-generator) scaffolds a Vite-based package for custom CKEditor 5 plugins. It gives you a starter plugin, a sample editor, tests, linting, translation tooling, and build scripts for npm and direct browser usage.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--what-the-generator-gives-you">

### What the generator gives you

JavaScript and TypeScript packages share the same development flow. Right after generation, you get:

* A starter plugin in `src/`.
* A local sample app in `sample/`, powered by Vite.
* Unit tests in `tests/`, powered by Vitest.
* Theme files in `theme/` for icons and CSS.
* Translation helpers in `lang/` and `scripts/`.
* Build scripts that create an npm package build and browser-ready files in `dist/`.

The TypeScript template also adds `src/augmentation.ts`, `tsconfig.json`, `tsconfig.build.json`, `typings/`, and generated declaration files.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--generate-a-package">

### Generate a package

You can run the generator without any arguments. If you do not pass some values on the command line, the CLI asks for them interactively:

```
npx ckeditor5-package-generator

```

This guide uses the following example names:

| Example value     | What it represents                                    |
| ----------------- | ----------------------------------------------------- |
| ckeditor5-callout | The package name entered in the generator.            |
| ckeditor5-callout | An example package name and generated directory name. |
| Callout           | The default plugin class name for ckeditor5-callout.  |
| CKCallout         | The suggested UMD global name for ckeditor5-callout.  |

Your actual names depend on the package name and on the values you confirm or pass for `--plugin-name` and `--global-name`.

The package name can use either of these formats:

* `@<scope>/ckeditor5-<name>`
* `ckeditor5-<name>`

Allowed characters are numbers (`0-9`), lowercase letters (`a-z`), and symbols: `-` `.` `_`.

The generator creates a new directory named after the package without the scope part. For example, both `ckeditor5-callout` and `@scope/ckeditor5-callout` create the `ckeditor5-callout/` directory.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--useful-options">

#### Useful options

| Option                              | What it changes                                                                                                                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| \--lang js or \--lang ts            | Pre-fills the programming language. If omitted, the generator asks interactively.                                                                                                                |
| \--plugin-name <name>               | Pre-fills the plugin class name.                                                                                                                                                                 |
| \--global-name <name>               | Pre-fills the UMD global name used by dist/browser/index.umd.js. If omitted, the generator still asks for it and suggests a name based on package name, such as CKCallout for ckeditor5-callout. |
| \--package-manager <npm\|yarn|pnpm> | Pre-fills the package manager choice. If omitted, the generator asks for it when multiple package managers are available; otherwise it uses npm.                                                 |
| \--verbose                          | Prints additional progress logs.                                                                                                                                                                 |

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--start-developing-the-package">

### Start developing the package

Enter the generated directory and start the sample app:

```
cd ckeditor5-callout
npm run start

```

The exact command prefix depends on the package manager you selected. The generated scripts are the same regardless of whether you run them with `npm`, `pnpm`, or `yarn`.

The most common scripts are:

| Command                          | What it does                                                |
| -------------------------------- | ----------------------------------------------------------- |
| npm run start                    | Starts the Vite sample app with live reload.                |
| npm run test                     | Runs the unit tests with Vitest.                            |
| npm run test:debug               | Runs Vitest in Node inspector mode.                         |
| npm run lint                     | Runs ESLint on the package sources.                         |
| npm run stylelint                | Runs Stylelint on theme/\*\*/\*.css.                        |
| npm run build                    | Creates the npm and browser builds in dist/.                |
| npm run translations:synchronize | Updates translation files from the current source messages. |
| npm run translations:validate    | Checks translation metadata without changing files.         |

When you start editing the generated package, the usual places to work in are:

* `src/` for the plugin code and public exports.
* `sample/index.[js|ts]` for the local editor setup used during development.
* `tests/` for unit tests.
* `theme/` for icons and CSS.
* `ckeditor5-metadata.json` for plugin metadata used by CKEditor 5 tooling.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--build-and-integrate-the-package">

### Build and integrate the package

Run `npm run build` when you want to publish the package or load it directly in the browser. The generator creates two kinds of output:

* An npm-oriented ESM build in `dist/`.
* A browser-oriented ESM and UMD build in `dist/browser/`.

See the [Build output and integration](#ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html) guide to learn what each file is for and how to use it with the [npm or ZIP quick start](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html) guide or the [CDN quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide.

<a id="ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html--next-steps">

### Next steps

* Follow the [Creating a basic plugin](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html) tutorial to build a real plugin on top of the generated template.
* Read the [localization](#ckeditor5/latest/framework/deep-dive/ui/localization.html) guide before adding translations.
* Use the [Build output and integration](#ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html) guide when you are ready to publish or embed the package.

<a id="ckeditor5/latest/framework/develpment-tools/testing-helpers.html">source file: "ckeditor5/latest/framework/develpment-tools/testing-helpers.html"</a>

## Testing helpers

The `_getModelData()` and `_setModelData()` functions exposed by [model developer utilities](../../api/module%5Fengine%5Fdev-utils%5Fmodel.html) and [view developer utilities](../../api/module%5Fengine%5Fdev-utils%5Fview.html) are useful development helpers.

They allow for “stringifying” the [model](#ckeditor5/latest/framework/architecture/editing-engine.html--model) and [view](#ckeditor5/latest/framework/architecture/editing-engine.html--view) structures, selections, ranges, and positions as well as for loading them from a string. They are often used when writing tests.

For instance, to take a peek at the editor model, you could use the [\_getModelData()](../../api/module%5Fengine%5Fdev-utils%5Fmodel.html#function-%5FgetModelData) helper:

See the [helper documentation](../../api/module%5Fengine%5Fdev-utils%5Fmodel.html#function-%5FgetModelData) to learn more about useful options.

<a id="ckeditor5/latest/framework/how-tos.html">source file: "ckeditor5/latest/framework/how-tos.html"</a>

## How-tos

<a id="ckeditor5/latest/framework/how-tos.html--basics">

### Basics

<a id="ckeditor5/latest/framework/how-tos.html--how-to-set-the-height-of-ckeditor-5">

#### How to set the height of CKEditor 5?

The height of the editing area can be easily controlled with CSS.

```
/* This selector targets the editable element (excluding comments). */
.ck-editor__editable_inline:not(.ck-comment__input *) {
    height: 300px;
    overflow-y: auto;
}

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-add-an-attribute-to-the-editor-editable-in-dom">

#### How to add an attribute to the editor editable in DOM?

If you have a reference to the editor instance, use the [change()](#ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-view) method of the view and set the new attribute via the [view downcast writer](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html):

```
editor.editing.view.change( writer => {
    const viewEditableRoot = editor.editing.view.document.getRoot();

    writer.setAttribute( 'myAttribute', 'value', viewEditableRoot );
} );

```

If you do not have the reference to the editor instance, but you have access to the editable element in the DOM, you can [access it using the ckeditorInstance property](#ckeditor5/latest/framework/how-tos.html--how-to-get-the-editor-instance-object-from-the-dom-element) and then use the same API to set the attribute:

```
const domEditableElement = document.querySelector( '.ck-editor__editable_inline' );
const editorInstance = domEditableElement.ckeditorInstance;

editorInstance.editing.view.change( writer => {
    // Map the editable element in the DOM to the editable element in the editor's view.
    const viewEditableRoot =
        editorInstance.editing.view.domConverter.mapDomToView(
            domEditableElement
        );

    writer.setAttribute( 'myAttribute', 'value', viewEditableRoot );
} );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-check-the-ckeditor-5-version">

#### How to check the CKEditor 5 version?

To check your editor version, open the JavaScript console available in the browser’s developer tools. This is usually done through the browser’s menu or by right-clicking anywhere on the page and choosing the `Inspect` option from the dropdown.

Enter the `CKEDITOR_VERSION` command to check the currently used CKEditor 5 version.

<a id="ckeditor5/latest/framework/how-tos.html--editors-instances">

### Editor’s instances

<a id="ckeditor5/latest/framework/how-tos.html--how-to-get-the-editor-instance-in-the-plugin">

#### How to get the editor instance in the plugin?

In a simple plugin, you can get the editor’s instance using a plugin functions’ attribute

```
function MyPlugin(editor) {
    // Interact with the API.
    // ...
}

ClassicEditor
    .create( {
        plugins: [
            MyPlugin,
            // Other plugins.
            // ...
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-get-the-editor-instance-object-from-the-dom-element">

#### How to get the editor instance object from the DOM element?

If you have a reference to the editor editable DOM element (the one with the `.ck-editor__editable` class and the `contenteditable` attribute), you can access the editor instance this editable element belongs to using the `ckeditorInstance` property:

```
<!-- The editable element in the editor's DOM structure. -->
<div class="... ck-editor__editable ..." contenteditable="true">
    <!-- Editable content. -->
</div>

```

```
// A reference to the editor editable element in the DOM.
const domEditableElement = document.querySelector( '.ck-editor__editable_inline' );

// Get the editor instance from the editable element.
const editorInstance = domEditableElement.ckeditorInstance;

// Use the editor instance API.
editorInstance.setData( '<p>Hello world!<p>' );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-list-all-instances-of-the-editor">

#### How to list all instances of the editor?

By default, CKEditor 5 has no global registry of editor instances. But if necessary, such a feature can be easily implemented, as explained in this [Stack Overflow answer](https://stackoverflow.com/a/48682501/1485219).

<a id="ckeditor5/latest/framework/how-tos.html--editors-api">

### Editor’s API

<a id="ckeditor5/latest/framework/how-tos.html--how-to-insert-some-content-into-the-editor">

#### How to insert some content into the editor?

Because CKEditor 5 uses a custom [data model](#ckeditor5/latest/framework/architecture/editing-engine.html), whenever you want to insert anything, you should modify the model first, which is then converted back to the view where the users input their content (called “editable”). In CKEditor 5, HTML is just one of many possible output formats. You can learn more about the ways of changing the model in the [dedicated guide](#ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-model).

For example, to insert a new link at the current position, use the following snippet:

```
editor.model.change( writer => {
    const insertPosition = editor.model.document.selection.getFirstPosition();

    const myLink = writer.createText(
        'CKEditor 5 rocks!',
        { linkHref: 'https://ckeditor.com/' }
    );

    editor.model.insertContent( myLink, insertPosition )
} );

```

And to insert some plain text, you can use a slightly shorter one:

```
editor.model.change( writer => {
    const insertPosition = editor.model.document.selection.getFirstPosition();

    editor.model.insertContent( writer.createText( 'Plain text' ), insertPosition );
} );

```

You may have noticed that a link is represented as a text with an attribute in the editor model. See the API of the [model writer](../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html) to learn about other useful methods that can help you modify the editor model. [model.insertContent](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) will ensure that the content can be inserted to the selected place according to the schema.

To insert some longer HTML code, you can parse it to the [model fragment](../api/module%5Fengine%5Fmodel%5Fdocumentfragment-ModelDocumentFragment.html) first and then [insert](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) it into the editor model:

```
const content =
    '<p>A paragraph with <a href="https://ckeditor.com">some link</a>.</p>';
const viewFragment = editor.data.processor.toView( content );
const modelFragment = editor.data.toModel( viewFragment );

editor.model.insertContent( modelFragment );

```

Remember, if some element or attribute does not have declared converters (whether by the dedicated feature or [General HTML support](#ckeditor5/latest/features/html/general-html-support.html)) plugin then those will not get inserted.

<a id="ckeditor5/latest/framework/how-tos.html--how-to-focus-the-editor">

#### How to focus the editor?

```
// Focus the editor.
editor.focus();

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-delete-selected-blocks">

#### How to delete selected blocks?

```
const selectedBlocks = Array.from(
    editor.model.document.selection.getSelectedBlocks()
);
const firstBlock = selectedBlocks[ 0 ];
const lastBlock = selectedBlocks[ selectedBlocks.length - 1 ];

editor.model.change( writer => {
    const range = writer.createRange(
        writer.createPositionAt( firstBlock, 0 ),
        writer.createPositionAt( lastBlock, 'end' )
    );

    const selection = writer.createSelection( range )

    editor.model.deleteContent( selection );
} );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-delete-all-specific-elements-like-block-images-in-the-editor">

#### How to delete all specific elements (like block images) in the editor?

```
editor.model.change( writer => {
    const range = writer.createRangeIn( editor.model.document.getRoot() );
    const itemsToRemove = [];

    for ( const value of range.getWalker() ) {
        if ( value.item.is( 'element', 'imageBlock' ) ) {
            // A different `is` usage.
            itemsToRemove.push( value.item );
        }
    }

    for ( const item of itemsToRemove ) {
        writer.remove( item ); // Remove all the items.
    }
} );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-place-the-caret-at-the-beginning-or-the-end">

#### How to place the caret at the beginning or the end?

```
// Place it at the beginning.
editor.model.change( writer => {
    writer.setSelection(
        writer.createPositionAt( editor.model.document.getRoot(), 0 )
    );
} );

// Place it at the end.
editor.model.change( writer => {
    writer.setSelection(
        writer.createPositionAt( editor.model.document.getRoot(), 'end' )
    );
} );

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-find-all-specific-elements-in-the-editor">

#### How to find all specific elements in the editor?

In the example below, we try to find all links, and store the unique ones.

```
const range = editor.model.createRangeIn( editor.model.document.getRoot() );

const links = new Set();

for ( const value of range.getWalker() ) {
    // Link is an attribute on a Text element.
    if ( value.type === 'text' && value.item.hasAttribute( 'linkHref' ) ) {
        // Set will store only unique links, preventing duplication.
        links.add( value.item.getAttribute( 'linkHref' ) );
    }
}

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-find-words-in-a-document-and-get-their-ranges">

#### How to find words in a document, and get their ranges?

If you need to search a text fragment and remap it to its model position, use the following example. It will find all words available in the document root, create a model range based on these and feed them into the console.

```
const model = editor.model;
const rootElement = model.document.getRoot();
const rootRange = model.createRangeIn( rootElement );
const wordRanges = [];

for ( const item of rootRange.getItems() ) {
    // Find `$block` elements (those accept text).
    if ( item.is( 'element' ) && model.schema.checkChild( item, '$text' ) ) {
        // Get the whole text from block.
        // Inline elements (like softBreak or imageInline) are replaced
        // with a single whitespace to keep the position offset correct.
        const blockText = Array.from( item.getChildren() )
            .reduce( ( rangeText, item ) => rangeText + ( item.is( '$text' ) ? item.data : ' ' ), '' );

        // Find all words.
        for ( const match of blockText.matchAll( /\b\S+\b/g ) ) {
            // The position in a text node is always parented by the block element.
            const startPosition = model.createPositionAt( item, match.index );
            const endPosition = model.createPositionAt( item, match.index + match[ 0 ].length );

            wordRanges.push( model.createRange( startPosition, endPosition ) );
        }
    }
}

// Example usage of the collected words:
for ( const range of wordRanges ) {
    const fragment = model.getSelectedContent( model.createSelection( range ) );
    const html = editor.data.stringify( fragment );

    console.log( `[${ range.start.path }] - [${ range.end.path }]`, html );
}

```

<a id="ckeditor5/latest/framework/how-tos.html--how-to-listen-on-a-double-click-for-example-link-elements">

#### How to listen on a double-click (for example, link elements)?

There are many observers provided with our features, and you should check if there is no conflicting observer that already fires for the given DOM event.

<a id="ckeditor5/latest/framework/how-tos.html--how-to-create-a-widget-with-a-single-view-element-and-multiplenested-model-elements">

#### How to create a widget with a single view element and multiple/nested model elements?

<a id="ckeditor5/latest/framework/how-tos.html--how-to-add-a-custom-button-to-the-link-dialog">

#### How to add a custom button to the link dialog?

<a id="ckeditor5/latest/framework/how-tos.html--framework-integrations">

### Framework integrations

<a id="ckeditor5/latest/framework/how-tos.html--the-javascript-heap-out-of-memory-error">

#### The `JavaScript heap out of memory` error

When building the React application for the production using the `npm run build` command, there is a faint chance it may produce an error related to the memory available on the build machine:

```
<--- Last few GCs --->

[32550:0x110008000]    42721 ms: Scavenge (reduce) 4061.0 (4069.6) -> 4060.5 (4070.8) MB, 4.3 / 0.0 ms  (average mu = 0.358, current mu = 0.374) allocation failure
[32550:0x110008000]    42726 ms: Scavenge (reduce) 4061.2 (4069.8) -> 4060.6 (4071.3) MB, 4.0 / 0.0 ms  (average mu = 0.358, current mu = 0.374) allocation failure
[32550:0x110008000]    42730 ms: Scavenge (reduce) 4061.4 (4073.3) -> 4060.9 (4073.3) MB, 3.7 / 0.0 ms  (average mu = 0.358, current mu = 0.374) allocation failure

<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
 1: 0x1012e4da5 node::Abort() (.cold.1) [/usr/local/bin/node]

```

This issue has not been fixed yet, however, there is a workaround for this. Increasing the available memory for Node.js using the `--max_old_space_size` modifier should resolve the problem.

```
node --max_old_space_size=4096 node_modules/.bin/react-scripts build

```

The memory limit can be set globally as well:

```
# Save it in the `.bash_profile` file to avoid typing it after rebooting the machine.
export NODE_OPTIONS="--max-old-space-size=4096"

npm run build

```

It can also be set on-demand, per command call:

```
NODE_OPTIONS="--max-old-space-size=4096" npm run build

```

<a id="ckeditor5/latest/framework/index.html">source file: "ckeditor5/latest/framework/index.html"</a>

## CKEditor 5 Framework overview

CKEditor 5 is a project that allows you to quickly and easily initialize one of the many types of editors it offers in your application. At the same time, it is a framework for creating custom-tailored rich-text editing solutions. The former requirement is met thanks to the editor type presets. The latter – thanks to CKEditor 5 Framework.

CKEditor 5 Framework is a highly-flexible and universal platform that provides a set of components allowing you to create any kind of rich text editing solution. It enables the building of different, custom-tailored editors that suit specific needs. It also provides tools for the creation and integration of user-made features and for customizing existing ones.

This guide explains how the framework is built and how to start using it.

Please note that the CKEditor 5 Framework documentation is constantly updated and expanded, but it may still be lacking some things. Feel free to [suggest documentation enhancements](https://github.com/ckeditor/ckeditor5/labels/type%3Adocs) and share your feedback about the framework.

If the documentation is insufficient, do not be afraid to look into the source code of [CKEditor 5 packages](https://github.com/ckeditor?utf8=%E2%9C%93&q=ckeditor5&type=public). For example, if you plan to create a new feature, check if a similar one already exists and try to take inspiration from its source code.

<a id="ckeditor5/latest/framework/index.html--when-to-use-the-framework">

### When to use the framework?

The CKEditor 5 Builder provides an easy way to create a custom-tailored installation, but certain types of customizations require using the framework.

* **Writing your own features.** New features are implemented using the framework.
* **Customizing existing features.** Changing the behavior or look of existing features can be done thanks to the framework’s capabilities.
* **Creating new types of editors.** You can create new editor types using the framework.

To sum up: you need to start using the framework as soon as existing builds do not meet your requirements or cannot be customized to the extent you need.

<a id="ckeditor5/latest/framework/index.html--contents-of-this-section">

### Contents of this section

This section of CKEditor 5 documentation provides the following resources accessible from the left-hand menu (or **main menu button in the upper-left corner** on mobile systems):

* Tutorials – A crash course, a basic tutorial and advanced guides for any developers keep on writing their own CKEditor 5 plugins.
* Development tools – A set of useful tooling and resources for anyone wanting to develop their editor.
* Architecture – Intro-duction to the main pillars of CKEditor 5’s architecture.
* Deep dive – Further Framework information for advanced developers.
* How-tos – If you just need to know how to set the height of CKEditor 5 or learn how to focus the editor, this is the right section!

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html">source file: "ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html"</a>

## Defining a model and a view

This guide will show you how to create a simple abbreviation plugin for CKEditor 5.

We will create a toolbar button that lets the users insert abbreviations into their document. These abbreviations will use the [<abbr> HTML element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr) with a ‘title’ attribute that will show up in a tooltip when the user hovers over the element. You can check the mechanism hovering over the underlined “HTML” text in the previous sentence.

This first part of the tutorial will cover the basics. We will just insert one possible abbreviation: “WYSIWYG.” We will get user input in the [next part of this tutorial series](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html).

If you want to see the final product of this tutorial before you plunge in, check out the [live demo](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--demo).

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--lets-start">

### Let’s start!

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/starter-files abbreviation-plugin
cd abbreviation-plugin

npm install
npm run dev

```

This will create a new directory called `abbreviation-plugin` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--plugin-structure">

### Plugin structure

Our abbreviation plugin is divided into three components – `Abbreviation`, `AbbreviationUI`, and `AbbreviationEditing`:

* `Abbreviation` will be the glue that holds the UI and the editing together.
* `AbbreviationUI` will be responsible for the UI – the toolbar button.
* `AbbreviationEditing` will enable the abbreviation attribute in the model and introduce a proper model ←→ view conversion.

We put them in the `/abbreviation` directory. We will be adding more files there in the next parts of the tutorial. This is our directory structure so far:

```
├── main.js
├── index.html
├── package.json
├── abbreviation
│   ├── abbreviation.js
│   ├── abbreviationediting.js
│   └── abbreviationui.js

```

Take a look at the 3 components, which have already been defined and imported into `main.js`.

`AbbreviationUI`:

```
// abbreviation/abbreviationui.js

import { Plugin } from 'ckeditor5';

export default class AbbreviationUI extends Plugin {
    init() {
        console.log( 'AbbreviationUI#init() got called' );
    }
}

```

`AbbreviationEditing`:

```
// abbreviation/abbreviationediting.js

import { Plugin } from 'ckeditor5';

export default class AbbreviationEditing extends Plugin {
    init() {
        console.log( 'AbbreviationEditing#init() got called' );
    }
}

```

`Abbreviation`:

```
// abbreviation/abbreviation.js

import AbbreviationEditing from './abbreviationediting';
import AbbreviationUI from './abbreviationui';
import { Plugin } from 'ckeditor5';

export default class Abbreviation extends Plugin {
    static get requires() {
        return [ AbbreviationEditing, AbbreviationUI ];
    }
}

```

Now, we need to load the `Abbreviation` plugin in our `main.js` file. The editor will load the `AbbreviationUI` and the `AbbreviationEditing` components by itself, as they are required by our “glue” plugin.

```
// main.js

import Abbreviation from './abbreviation/abbreviation';					// ADDED

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic,
            Abbreviation												// ADDED
        ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ]
    } );

```

You should see that the `AbbreviationEditing` and `AbbreviationUI` plugins were loaded.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--the-model-and-the-view-layers">

### The model and the view layers

CKEditor 5 implements its own custom data model, which does not map 1:1 to the DOM. The model document is converted into the view, which represents the content that the user is editing.

In the view layer, we will have the `<abbr>` HTML element, with the title attribute. See what it will look like in the inspector.

In the model, inline elements such as `<abbr>`, are represented as attributes not as separate elements. In order for our plugin to work, we will need to make sure that we can add abbreviation attribute to the text node.  

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--defining-the-schema">

#### Defining the schema

We can do it by defining the model’s schema. With to a couple lines of code, we will allow all text nodes to receive the model abbreviation attribute.

We will simply extend the text node’s schema to accept our abbreviation attribute using the `schema.extend()` method.

Update the `AbbreviationEditing` plugin with this definition:

```
// abbreviation/abbreviationediting.js

import { Plugin } from 'ckeditor5';

export default class AbbreviationEditing extends Plugin {
    init() {
        this._defineSchema();									// ADDED
    }

    _defineSchema() {											// ADDED
        const schema = this.editor.model.schema;

        // Extend the text node's schema to accept the abbreviation attribute.
        schema.extend( '$text', {
            allowAttributes: [ 'abbreviation' ]
        } );
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--defining-converters">

#### Defining converters

Converters tell the editor how to transform the view to the model (for example, when loading the data to the editor or handling pasted content) and how to render the model to the view (for editing purposes or when retrieving the editor data).

We will need to convert the model abbreviation attribute into a view element (downcast) and vice versa (upcast). We can achieve this by using our [conversion helpers](#ckeditor5/latest/framework/deep-dive/conversion/helpers/intro.html) and defining what the model and the view is supposed to look like for both conversions.

Converting the full title of the abbreviation is a little bit tricky, because we need to make sure that its value is synchronized between the model and the view.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--downcast-conversion">

##### Downcast conversion

In the downcast conversion, we will use one of our conversion helpers – [attributeToElement()](#ckeditor5/latest/framework/deep-dive/conversion/helpers/downcast.html--attribute-to-element-conversion-helper) – to transform the model abbreviation attribute into the view `<abbr>` element.

We will need to use a callback function to get the title stored as a model attribute value and transform it into the title value of the view element. Here, the second parameter of the view callback is the `DowncastConversionApi` object. We will use its `writer` property, which will allow us to manipulate the data during downcast conversion, as it contains an instance of the `ViewDowncastWriter`.

```
// abbreviation/abbreviationediting.js

import { Plugin } from 'ckeditor5';

export default class AbbreviationEditing extends Plugin {
    init() {
        this._defineSchema();
        this._defineConverters();							// ADDED
    }

    _defineSchema() {
        // Previously defined schema.
        // ...
    }

    _defineConverters() {									// ADDED
        const conversion = this.editor.conversion;

        // Conversion from a model attribute to a view element.
        conversion.for( 'downcast' ).attributeToElement( {
            model: 'abbreviation',
            // Callback function provides access to the model attribute value
            // and the ViewDowncastWriter.
            view: ( modelAttributeValue, conversionApi ) => {
                const { writer } = conversionApi;

                return writer.createAttributeElement( 'abbr', {
                    title: modelAttributeValue
                } );
            }
        } );

    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--upcast-conversion">

##### Upcast conversion

The upcast conversion tells the editor how the view `<abbr>` element is supposed to look like in the model. We will transform it using another conversion helper – [elementToAttribute()](#ckeditor5/latest/framework/deep-dive/conversion/helpers/upcast.html--element-to-attribute-conversion-helper).

We also need to grab the title value from the content and use it in the model. We can do that thanks to a callback function, which gives us the access to the view element.

```
// abbreviation/abbreviationediting.js

import { Plugin } from 'ckeditor5';

export default class AbbreviationEditing extends Plugin {
    init() {
        // Schema and converters initialization.
        // ...
    }

    _defineSchema() {
        // Previously defined schema.
        // ...
    }

    _defineConverters() {
        const conversion = this.editor.conversion;

        conversion.for( 'downcast' ).attributeToElement(
            // Code responsible for downcast conversion.
            // ...
        );

        // Conversion from a view element to a model attribute.
        conversion.for( 'upcast' ).elementToAttribute( {
            view: {
                name: 'abbr',
                attributes: [ 'title' ]
            },
            model: {
                key: 'abbreviation',
                // Callback function provides access to the view element.
                value: viewElement => {
                    const title = viewElement.getAttribute( 'title' );

                    return title;
                }
            }
        } );
    }
}

```

Thanks to the upcast conversion, our abbreviation added in the `index.html` should work now. The changes should be visible after the development server refresh.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--creating-a-toolbar-button">

### Creating a toolbar button

Now we can create our Abbreviation toolbar button using the [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) class.

We need to register it in the editor’s UI `componentFactory`, so it can be displayed in the toolbar.

```
// abbreviation/abbreviationui.js

import { ButtonView, Plugin } from 'ckeditor5';

export default class AbbreviationUI extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'abbreviation', () => {
            const button = new ButtonView();

            button.label = 'Abbreviation';
            button.tooltip = true;
            button.withText = true;

            return button;
        } );
    }
}

```

We passed the name of the button in the `componentFactory.add`, so it is now available to use in the toolbar configuration. We can now simply add it to the toolbar in `main.js`:

```
// main.js

import Abbreviation from './abbreviation/abbreviation';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic, Abbreviation
        ],
        toolbar: [
            'heading', 'bold', 'italic', 'numberedList', 'bulletedList',
            '|',
            'abbreviation'												 // ADDED
        ]
    } );

```

We have the button, so let’s define what should happen after the user clicks it.

We will use the `insertContent()` method to insert our abbreviation and its title attribute into the document. Inside, we just need to create a new text node with `writer.createText()`.

```
// abbreviation/abbreviationui.js

import { ButtonView, Plugin } from 'ckeditor5';

export default class AbbreviationUI extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'abbreviation', () => {
            // Previously initialized button view.
            // ...

            this.listenTo( button, 'execute', () => {
                const selection = editor.model.document.selection;
                const title = 'What You See Is What You Get';
                const abbr = 'WYSIWYG';

                // Change the model to insert the abbreviation.
                editor.model.change( writer => {
                    editor.model.insertContent(
                        // Create a text node with the abbreviation attribute.
                        writer.createText( abbr, { abbreviation: title } )
                    );
                } );
            } );

            return button;
        } );
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--demo">

### Demo

Here you can see the result in action.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--final-code">

### Final code

If you got lost at any point, this is [the final implementation of the plugin](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/part-1). You can paste the code from different files into your project, or clone and install the whole thing, and it will run out-of-the-box.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. But do not install the dependencies. Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Therefore, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html">source file: "ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html"</a>

## Getting user input with a custom UI

In this part of the tutorial we will focus on creating a dialog, which will get the user’s input.

We will pick up where we left off in the first part, so make sure you [start there](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html) or grab our starter files for this part using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/part-1 abbreviation-plugin
cd abbreviation-plugin

npm install
npm run dev

```

If you want to see the final product of this tutorial before you plunge in, check out the [live demo](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--demo).

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--creating-a-view">

### Creating a view

The most important part of the UI for this plugin is a dialog with a form, which will get us the user’s input.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--creating-a-form-view-template">

#### Creating a form view template

Let’s start by creating a view with a form. It will include two input fields (for the abbreviation and the title), as well as the Submit and Cancel buttons. We will do it in a separate view. First, we create a new file `abbreviationview.js` in the `abbreviation/` directory.

Our new `FormView` class will extend the [View](#ckeditor5/latest/framework/architecture/ui-library.html--views) class, so let’s start by importing it from the UI library.

In the `FormView` constructor we define a template for our abbreviation form. We need to set the tag of the HTML element, and a couple of its attributes. To make sure our view is focusable, let’s add [tabindex="-1"](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--implementing-focusable-ui-components).

```
// abbreviation/abbreviationview.js

import { View } from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {
        super( locale );

        this.setTemplate( {
            tag: 'form',
            attributes: {
                class: [ 'ck', 'ck-abbr-form' ],
                tabindex: '-1'
            }
        } );
    }

}

```

Notice that we added two classes. All UI elements of the editor need to have the `ck` class (unless you want to create your own UI and not use CKEditor 5’s built-in library). We also created a new class for our form, which we will use later on to style it.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--creating-input-fields">

#### Creating input fields

As we have two similar input fields to create and we do not want to repeat ourselves, let’s define a method `_createInput()`, which will produce them for us. It will accept the label of our input field.

We will use [LabeledFieldView](../../../api/module%5Fui%5Flabeledfield%5Flabeledfieldview-LabeledFieldView.html) class and we will pass it the [createLabeledInputText()](../../../api/module%5Fui%5Flabeledfield%5Futils.html#constant-createLabeledInputText) function as the second argument. It is a helper coming from the CKEditor UI library that will take care of creating the input.

```
// abbreviation/abbreviationview.js

import {
    View,
    LabeledFieldView,				// ADDED
    createLabeledInputText			// ADDED
} from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {

        this.abbrInputView = this._createInput( 'Add abbreviation' );
        this.titleInputView = this._createInput( 'Add title' );

        // Previously set template.
        // ...
    }

    _createInput( label ) {
        const labeledInput = new LabeledFieldView( this.locale, createLabeledInputText );

        labeledInput.label = label;

        return labeledInput;
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--creating-form-buttons">

#### Creating form buttons

Now, we add the Submit and Cancel buttons to our form. You can start by importing `ButtonView` from our UI library together with the icons, which we will use for labels.

We will use the `check` and `cancel` icons from the core package’s [icons library](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-icons). After importing the icons, we will use them for creating the buttons.

Let’s write a `_createButton` function, which will take three arguments – `label`, `icon` and `className`. We then set the button attributes, using the properties we passed into the function before, and adding a tooltip option.

```
// abbreviation/abbreviationview.js

import {
    View,
    LabeledFieldView,
    createLabeledInputText,
    ButtonView,		// ADDED
    IconCheck,		// ADDED
    IconCancel		// ADDED
} from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {
        // Previously created inputs.
        // ...

        // Create the save and cancel buttons.
        this.saveButtonView = this._createButton(
            'Save', IconCheck, 'ck-button-save'
        );
        // Set the type to 'submit', which will trigger
        // the submit event on entire form when clicked.
        this.saveButtonView.type = 'submit';

        this.cancelButtonView = this._createButton(
            'Cancel', IconCancel, 'ck-button-cancel'
        );

        // Previously set template.
        // ...
    }

    _createInput( label ) {
        // Input initialization.
        // ...
    }

    _createButton( label, icon, className ) {
        const button = new ButtonView();

        button.set( {
            label,
            icon,
            tooltip: true,
            class: className
        } );

        return button;
    }
}

```

When the user clicks one of these buttons, we want to either submit or cancel the form view. These events should be fired off from the form view, so we need to delegate them from the buttons to the form view.

For now, we delegate `cancelButtonView#execute` to the FormView, so pressing the Cancel button will fire off `FormView#cancel`. We will handle delegating the submit event in a couple of steps.

```
// abbreviation/abbreviationview.js

// Previously imported packages.
// ...

export default class FormView extends View {
    constructor( locale ) {
        // Previously created inputs.
        // ...

        this.saveButtonView = this._createButton(
            'Save', IconCheck, 'ck-button-save'
        );
        this.saveButtonView.type = 'submit';
        this.cancelButtonView = this._createButton(
            'Cancel', IconCancel, 'ck-button-cancel'
        );
        // Delegate ButtonView#execute to FormView#cancel.
        this.cancelButtonView.delegate( 'execute' ).to( this, 'cancel' );

        // Previously set template.
        // ...
    }

    _createInput( label ) {
        // Input initialization.
        // ...
    }

    _createButton( label, icon, className ) {
        // Button initialization.
        // ...
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--adding-styles">

#### Adding styles

We use `styles.css` to style the new UI elements. Let’s add some padding to our form and use the [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) to nicely display all four elements of the form.

We will use our set spacing variables to keep things uniform.

```
/* style.css */

.ck.ck-abbr-form {
    padding: var(--ck-spacing-large);
    display: grid;
    grid-template-columns: repeat(2, 1fr);
    grid-template-rows: repeat(3, 1fr);
    grid-column-gap: 0px;
    grid-row-gap: var(--ck-spacing-standard);
}

.ck.ck-abbr-form .ck.ck-labeled-field-view:nth-of-type(1) {
    grid-area: 1 / 1 / 2 / 3;
}

.ck.ck-abbr-form .ck.ck-labeled-field-view:nth-of-type(2) {
    grid-area: 2 / 1 / 3 / 3;
}

.ck.ck-abbr-form .ck-button:nth-of-type(1) {
    grid-area: 3 / 1 / 4 / 2;
}

.ck.ck-abbr-form .ck-button:nth-of-type(2) {
    grid-area: 3 / 2 / 4 / 3;
}


```

Import it into `AbbreviationUI`:

```
// abbreviation/abbreviationui.js

import { ButtonView, Plugin } from 'ckeditor5';
import './styles.css';		// ADDED

export default class AbbreviationUI extends Plugin {
    // Definition of Abbreviation UI class.
    // ...
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--wrapping-up-the-form-view">

#### Wrapping up the form view

We are almost done with the form view, we just need to add a couple of finishing touches.

In the `constructor`, we create a [ViewCollection](../../../api/module%5Fui%5Fviewcollection-ViewCollection.html) with the `createCollection()` method. We put all our input and button views in the collection, and use it to update the `FormView` template with its newly created children.

Let’s also add `render()` method to our `FormView`. We will use a helper `submitHandler()` function there, which intercepts a native DOM submit event, prevents the default web browser behavior (navigation and page reload) and fires the `submit` event on a view instead.

We also need a `focus()` method, which will focus on the first child of our `abbreviation` input view each time the form is added to the editor. This is just a taste of what [focus tracking](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html) can do in CKEditor 5\. We will get into it more in next part of this tutorial.

```
// abbreviation/abbreviationview.js

import {
    View,
    LabeledFieldView,
    createLabeledInputText,
    ButtonView,
    IconCheck,
    submitHandler,	// ADDED
} from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {
        // Previously created elements.
        // ...

        this.childViews = this.createCollection( [
            this.abbrInputView,
            this.titleInputView,
            this.saveButtonView,
            this.cancelButtonView
        ] );

        this.setTemplate( {
            tag: 'form',
            attributes: {
                // Attributes of a form template.
                // ...
            },
            children: this.childViews	// ADDED
        } );
    }

    render() {
        super.render();

        // Submit the form when the user clicked the save button
        // or pressed enter in the input.
        submitHandler( {
            view: this
        } );
    }

    focus() {
        this.childViews.first.focus();
    }

    _createInput( label ) {
        // Input initialization.
        // ...
    }

    _createButton( label, icon, className ) {
        // Button initialization.
        // ...
    }
}

```

Our `FormView` is done! However, we cannot see it just yet, so let’s add it to our `AbbreviationUI` class.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--adding-the-contextual-balloon">

### Adding the Contextual Balloon

Our form needs to appear in a balloon, and we will use the [ContextualBalloon](../../../api/module%5Fui%5Fpanel%5Fballoon%5Fcontextualballoon-ContextualBalloon.html) class from the CKEditor 5 UI library to make one.

This is where we ended up with our UI in the first part of the tutorial.

```
// abbreviation/abbreviationui.js

import { ButtonView, Plugin } from 'ckeditor5';

export default class AbbreviationUI extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'abbreviation', () => {
            const button = new ButtonView();

            button.label = 'Abbreviation';
            button.tooltip = true;
            button.withText = true;

            this.listenTo( button, 'execute', () => {
                const title = 'What You See Is What You Get';
                const abbr = 'WYSIWYG';

                editor.model.change( writer => {
                    editor.model.insertContent(
                        writer.createText( abbr ),
                        { 'abbreviation': title }
                    );

                } );
            } );

            return button;
        } );
    }
}

```

We will need to change it quite a bit and add `ContextualBalloon` and `FormView`. We need to make sure Contextual Balloon is required when making an instance of our `AbbreviationUI`, so we will start with that.

Let’s write a basic `_createFormView()` function, just to create an instance of our `FormView` class (we will expand it later).

We also need to create a function, which will give us the target position for our balloon from user’s selection. We need to convert the selected view range into DOM range. We can use the `viewRangeToDom()` method to do so.

Finally, we add our balloon and the form view to the `init()` method.

```
// abbreviation/abbreviationui.js

import {
    ButtonView,
    ContextualBalloon,						// ADDED
    Plugin
} from 'ckeditor5';
import FormView from './abbreviationview';	// ADDED

export default class AbbreviationUI extends Plugin {
    static get requires() {
        return [ ContextualBalloon ];
    }

    init() {
        const editor = this.editor;

        // Create the balloon and the form view.
        this._balloon = this.editor.plugins.get( ContextualBalloon );
        this.formView = this._createFormView();

        editor.ui.componentFactory.add( 'abbreviation', () => {
            // A component factory callback that creates a button.
            // ...
        } );
    }

    _createFormView() {
        const editor = this.editor;
        const formView = new FormView( editor.locale );

        return formView;
    }

    _getBalloonPositionData() {
        const view = this.editor.editing.view;
        const viewDocument = view.document;
        let target = null;

        // Set a target position by converting view selection range to DOM.
        target = () => view.domConverter.viewRangeToDom(
            viewDocument.selection.getFirstRange()
        );

        return {
            target
        };
    }
}

```

We can now change what happens when the user clicks the toolbar button. We will replace inserting the hard-coded abbreviation with the one defined by the user.

Let’s write a `_showUI()` method which will show our UI elements by adding the form view to our balloon and setting its position. The last thing is to focus the form view, so the user can immediately start typing in the first input field.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

export default class AbbreviationUI extends Plugin {
    // More methods.
    // ...

    init() {
        // The balloon and the view initialization.
        // ...

        editor.ui.componentFactory.add( 'abbreviation', () => {
            // Button initialization.
            // ...

            // Show the UI on button click.
            this.listenTo( button, 'execute', () => {
                this._showUI();
            } );

            return button;
        } );
    }

    _createFormView() {
        // The form view initialization.
        // ...
    }

    _getBalloonPositionData() {
        // Getting position data for the balloon.
        // ...
    }

    _showUI() {
        this._balloon.add( {
            view: this.formView,
            position: this._getBalloonPositionData()
        } );

        this.formView.focus();
    }
}

```

You should be able to see your balloon and form now! Check and see your balloon pop up (we will get to hiding it soon). It should look like this:

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--getting-user-input">

### Getting user input

Now is the time to replace the hard-coded “WYSIWYG” abbreviation with the user input. We will be getting values from the form and listening to the `submit` event on the form view, which we delegated from the Save button (with the help of `submitHandler`).

We use the same callback function we had in the toolbar button in the first part of the tutorial. We just need to replace the “WYSIWYG” abbreviation with values from our input views.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

export default class AbbreviationUI extends Plugin {
    static get requires() {
        return [ ContextualBalloon ];
    }

    init() {
        // The balloon and the view initialization.
        // ...
    }

    _createFormView() {
        const editor = this.editor;
        const formView = new FormView( editor.locale );

        this.listenTo( formView, 'submit', () => {
            const title = formView.titleInputView.fieldView.element.value;
            const abbr = formView.abbrInputView.fieldView.element.value;

            editor.model.change( writer => {
                editor.model.insertContent(
                    writer.createText( abbr, { abbreviation: title } )
                );
            } );

        } );

        return formView;
    }

    _getBalloonPositionData() {
        // Getting position data for the balloon.
        // ...
    }

    _showUI() {
        // Displaying balloon for the user.
        // ...
    }
}

```

Our plugin is finally doing what it is supposed to. The last thing is to hide it from our editor when we do not need it.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--hiding-the-form-view">

### Hiding the form view

We will need to hide the form view in these three situations:

* after the user submits the form;
* when the user clicks the Cancel button;
* when the user clicks outside of the balloon.

We will write a simple `_hideUI()` function, which will clear the input field values and remove the view from our balloon.

Additionally, we will import the `clickOutsideHandler()` method, which will take our `_hideUI()` function as a callback. It will be emitted from our form view, and activated when the form view is visible. We also need to set `contextElements` for the handler to determine its scope. Clicking on HTML elements listed there will not fire the callback.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

import { ContextualBalloon, clickOutsideHandler } from 'ckeditor5'; // ADDED

export default class AbbreviationUI extends Plugin {
    static get requires() {
        return [ ContextualBalloon ];
    }

    init() {
        // The balloon and the view initialization.
        // ...
    }

    _createFormView() {
        const editor = this.editor;
        const formView = new FormView( editor.locale );

        this.listenTo( formView, 'submit', () => {
            // Setting texts: title and abbreviation.
            // ...

            // Hide the form view after submit.
            this._hideUI();
        } );

        // Hide the form view after clicking the "Cancel" button.
        this.listenTo( formView, 'cancel', () => {
            this._hideUI();
        } );

        // Hide the form view when clicking outside the balloon.
        clickOutsideHandler( {
            emitter: formView,
            activator: () => this._balloon.visibleView === formView,
            contextElements: [ this._balloon.view.element ],
            callback: () => this._hideUI()
        } );

        return formView;
    }

    _hideUI() {
        this.formView.abbrInputView.fieldView.value = '';
        this.formView.titleInputView.fieldView.value = '';
        this.formView.element.reset();

        this._balloon.remove( this.formView );

        // Focus the editing view after closing the form view.
        this.editor.editing.view.focus();
    }

    _getBalloonPositionData() {
        // Getting position data for the balloon.
        // ...
    }

    _showUI() {
        // Displaying balloon for the user.
        // ...
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--demo">

### Demo

See the result in action.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html--final-code">

### Final code

If you got lost at any point, this is [the final implementation of the plugin](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/part-2). You can paste the code from different files into your project, or clone and install the whole thing, and it will run out-of-the-box.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html">source file: "ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html"</a>

## Improving accessibility and adding a command

You made it to the final part of the abbreviation plugin tutorial. In this part, we will improve accessibility of our plugin. We will also work on a command, which will additionally grab the text from user’s selection, and insert it into our form. And more!

We pick up where we left off in the [second part](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html), so make sure you finished it, or grab our starter files for this part using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/abbreviation-plugin/part-2 abbreviation-plugin
cd abbreviation-plugin

npm install
npm run dev

```

If you want to see the final product of this tutorial before you plunge in, check out the [live demo](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--demo).

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--improving-accessibility">

### Improving accessibility

First, we make our plugin accessible for users who rely on keyboards for navigation. We want to ensure that pressing Tab and Shift \+ Tab will move focus around in the form view, and pressing Esc will close it.

We have some ready-to-use options to help us out – the [KeystrokeHandler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-keystrokehandler-class), [FocusTracker](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focustracker-class), and [FocusCycler](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html--using-the-focuscycler-class) helper classes.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--adding-a-keystroke-handler-and-a-focus-tracker">

#### Adding a keystroke handler and a focus tracker

We start by importing the `KeystrokeHandler` and `FocusTracker` classes into our form view, and creating their new instances in the `constructor()`.

Now, in the `render()` method, we add each element of our `childViews` view collection to the `focusTracker`. There, we can also start listening for the keystrokes coming from the rendered view element.

Finally let’s add the `destroy()` method, and destroy both the focus tracker and the keystroke handler. It will ensure that when the user kills the editor, our helpers “die” too, preventing any memory leaks.

```
// abbreviation/abbreviationview.js

import {
    View,
    LabeledFieldView,
    createLabeledInputText,
    ButtonView,
    submitHandler,
    IconCheck,
    FocusTracker,		// ADDED
    KeystrokeHandler,	// ADDED
} from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {
        // View class constructor invoke.
        // ...

        this.focusTracker = new FocusTracker();
        this.keystrokes = new KeystrokeHandler();

        // Code prepared in the previous part.
        // ...
    }

    render() {
        // View.render() invocation and adding a submit handler.
        // ...

        this.childViews._items.forEach( view => {
            // Register the view in the focus tracker.
            this.focusTracker.add( view.element );
        } );

        // Start listening for the keystrokes coming from #element.
        this.keystrokes.listenTo( this.element );
    }

    destroy() {
        super.destroy();

        this.focusTracker.destroy();
        this.keystrokes.destroy();
    }

    // Previously declared helper methods.
    // ...
}

```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--adding-a-focus-cycler">

#### Adding a focus cycler

The `FocusCycler` will allow the user to navigate through all the children of our form view, cycling over them. Check how our navigation works now in our form view – we can use Tab to move from the first input field to the second, but then the focus leaves the form, and the editor itself. Let’s fix that.

We import the `FocusCycler` class, and create its instance in the form view `constructor()`. We need to pass an object with focusables (so our `childViews` collection), the focus tracker, the keystroke handler, and the actions connected to different keystrokes.

```
// abbreviation/abbreviationview.js

import {
    View,
    LabeledFieldView,
    createLabeledInputText,
    ButtonView,
    submitHandler,
    FocusTracker,
    KeystrokeHandler,
    icons,
    FocusCycler		// ADDED
} from 'ckeditor5';

export default class FormView extends View {
    constructor( locale ) {

        // Previous code from the constructor.
        // ...

        this._focusCycler = new FocusCycler( {
            focusables: this.childViews,
            focusTracker: this.focusTracker,
            keystrokeHandler: this.keystrokes,
            actions: {
                // Navigate form fields backwards using the Shift + Tab keystroke.
                focusPrevious: 'shift + tab',

                // Navigate form fields forwards using the Tab key.
                focusNext: 'tab'
            }
        } );

        this.setTemplate( {
            // Setting the form template.
            // ...
        } );
    }

    // Previously declared methods.
    // ...
}

```

Now we can add the Esc button handler in our `_createFromView()` function, which will hide the UI and fire off `cancel` on the form.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

export default class AbbreviationUI extends Plugin {
    // Previously declared methods.
    // ...

    _createFormView() {
        // Form view initialization.
        // ...

        // Close the panel on esc key press when the form has focus.
        formView.keystrokes.set( 'Esc', ( data, cancel ) => {
            this._hideUI();
            cancel();
        } );

        return formView;
    }

    // Previously declared helper methods.
    // ...
}

```

We are done with improving accessibility for keyboard-only users. Try it out yourself by pressing Tab, Shift \+ Tab, and Esc in the form.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--improving-the-ui-functionalities">

### Improving the UI functionalities

When the user selects a range (a letter, a word, or a whole document fragment) and presses the abbreviation button, they might expect that their selected text appears automatically in the abbreviation input field. Let’s add this functionality to our form.

To display the text from the user’s selection in the form field, we need to first grab and concatenate all text from the selected range. If the user selects a couple of paragraphs, a heading, and an image, we need to go through all the nodes, and use only the ones containing text.

Let’s create a helper `getRangeText()` function in a separate `/utils.js` file. It will grab all items from a range using its `getItems()` method. Then, it will concatenate all text from the [text](../../../api/module%5Fengine%5Fmodel%5Ftext-ModelText.html) and [textProxy](../../../api/module%5Fengine%5Fmodel%5Ftextproxy-ModelTextProxy.html) nodes, and skip all the others.

```
// abbreviation/utils.js

// A helper function that retrieves and concatenates all text within the model range.
export default function getRangeText( range ) {
    return Array.from( range.getItems() ).reduce( ( rangeText, node ) => {
        if ( !( node.is( 'text' ) || node.is( 'textProxy' ) ) ) {
            return rangeText;
        }

        return rangeText + node.data;
    }, '' );
}


```

Now, in `AbbreviationUI` we can adjust the `_showUI()` method to display the selected text in the abbreviation input field. We import `getRangeText` and pass the first range in the selection (using the `getFirstRange()` method) as an argument.

We will also disable the input field when the selection is not collapsed, because it would be hard to change the text of the abbreviation if the selection spans multiple paragraphs.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

import getRangeText from './utils.js';

export default class AbbreviationUI extends Plugin {
    // Previously declared methods.
    // ...

    _showUI() {
        const selection = this.editor.model.document.selection;

        this._balloon.add( {
            view: this.formView,
            position: this._getBalloonPositionData()
        } );

        // Disable the input when the selection is not collapsed.
        this.formView.abbrInputView.isEnabled = selection.getFirstRange().isCollapsed;

        const selectedText = getRangeText( selection.getFirstRange() );
        this.formView.abbrInputView.fieldView.value = selectedText;
        this.formView.titleInputView.fieldView.value = '';

        this.formView.focus();
    }

    // Previously declared helper methods.
    // ...
}

```

Since we are disabling the first input field in some cases, let’s update the `focus()` method in our form view accordingly.

```
// abbreviation/abbreviationview.js

// Previously imported packages.
// ...

export default class FormView extends View {
    // Previously declared constructor and other methods.
    // ...

    focus() {
        // If the abbreviation text field is enabled, focus it.
        if ( this.abbrInputView.isEnabled ) {
            this.abbrInputView.focus();
        }
        // Focus the abbreviation title field if the former is disabled.
        else {
            this.titleInputView.focus();
        }
    }

    // Previously declared helper methods.
    // ...
}

```

Our new functionality should work now, check it out yourself! It does not recognize whether the selected text is an abbreviation already, so if you select “WYSIWYG,” the full title does not yet appear in the title input field. We will change it in the next steps.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--adding-a-command">

### Adding a command

Our plugin does what we want it to do, so why complicate things by adding a command? Well, a command not only executes an action but also automatically reacts when any changes are applied to the model.

When the user makes a selection in the editor, the command will automatically check if there is an abbreviation there. It will also ensure that the command is only enabled where the “abbreviation” attribute can be set on the current model selection (not on images, for instance).

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--creating-a-command">

#### Creating a command

Let’s start by creating the command, and moving the existing action logic there.

In the `/abbreviationcommand.js` file, we import the `Command` class and create its instance.

We will start by simply moving there the action we already created for `submit` in our `_createFormView()` method, passing the title and the abbreviation text into the command’s `execute()` method.

```
// abbreviation/abbreviationcommand.js

import { Command } from 'ckeditor5';

export default class AbbreviationCommand extends Command {
    execute( { title, abbr } ) {
        const model = this.editor.model;

        model.change( writer => {
            model.insertContent(
                writer.createText( abbr, { abbreviation: title } )
            );
        } );

    }
}

```

Now, let’s initialize our `AbbreviationCommand`, by adding it to the list of editor’s commands in `AbbreviationEditing`. We will also pass a name there, that we will use to call our command.

```
// abreviation/abbreviationediting.js

import { Plugin } from 'ckeditor5';
import AbbreviationCommand from './abbreviationcommand';	// ADDED

export default class AbbreviationEditing extends Plugin {
    init() {
        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add(
            'addAbbreviation', new AbbreviationCommand( this.editor )
        );
    }

    // Previously declared methods.
    // ...
}

```

We can now replace the action called on `submit` with our new command, passing it into editor’s `execute()` method, along with the abbreviation and title values.

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

export default class AbbreviationUI extends Plugin {
    // Previously declared methods.
    // ...

    _createFormView() {
        const editor = this.editor;
        const formView = new FormView( editor.locale );

        // Execute the command after clicking the "Save" button.
        this.listenTo( formView, 'submit', () => {
            const value = {
                abbr: formView.abbrInputView.fieldView.element.value,
                title: formView.titleInputView.fieldView.element.value
            };
            editor.execute( 'addAbbreviation', value );

            this._hideUI();
        } );

        // Handle clicking outside the balloon and on the "Cancel" button.
        // ...
    }

    // Previously declared helper methods.
    // ...
}

```

The command should now work, and pressing the Submit button should have the same effect as it did before. We can now explore some additional functionalities. You can check it out now in the CKEditor 5 Inspector.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--refreshing-the-state">

#### Refreshing the state

Thanks to the command’s `refresh()` method, we can observe the state and the value of our command not just when the user presses the button, but whenever any changes are made in the editor. We will use this to check if the user’s selection has an abbreviation model attribute already.

Before we do that, we may want to check if the command can be used at all on a given selection. If the user selects an image, the command should be disabled. Let’s check if our `abbreviation` attribute is allowed in the schema, using its `checkAttributeInSelection()` method.

```
// abbreviation/abbreviationcommand.js

import { Command } from 'ckeditor5';

export default class AbbreviationCommand extends Command {
    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;

        // The command is enabled when the "abbreviation" attribute
        // can be set on the current model selection.
        this.isEnabled = model.schema.checkAttributeInSelection(
            selection, 'abbreviation'
        );
    }

    execute( { title, abbr } ) {
        // The code runs after command execution.
        // ...
    }
}

```

We can now check if the selected range is collapsed. If so, we will check if the caret is in an abbreviation, and grab the entire range containing it. We can easily do so using the [findAttributeRange](../../../api/module%5Ftyping%5Futils%5Ffindattributerange.html#function-findAttributeRange) helper function. We need to pass it the first position of the selection, our attribute name and value, and the model.

Then, we change the value of the command. We will get the abbreviation text using our `getRangeText` helper function. We also add a range value, which we will use when executing the command.

```
// abbreviation/abbreviationcommand.js

import {
    Command,
    findAttributeRange						// ADDED
} from 'ckeditor5';
import getRangeText from './utils.js';		// ADDED

export default class AbbreviationCommand extends Command {
    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;
        const firstRange = selection.getFirstRange();

        // When the selection is collapsed, the command has a value
        // if the caret is in an abbreviation.
        if ( firstRange.isCollapsed ) {
            if ( selection.hasAttribute( 'abbreviation' ) ) {
                const attributeValue = selection.getAttribute( 'abbreviation' );

                // Find the entire range containing the abbreviation
                // under the caret position.
                const abbreviationRange = findAttributeRange(
                    selection.getFirstPosition(), 'abbreviation', attributeValue, model
                );

                this.value = {
                    abbr: getRangeText( abbreviationRange ),
                    title: attributeValue,
                    range: abbreviationRange
                };
            } else {
                this.value = null;
            }
        }

        // The code that enables the command.
        // ...
    }

    execute( { title, abbr } ) {
        // The code runs after command execution.
        // ...
    }
}

```

If the selection is not collapsed, we check if it has the `abbreviation` model attribute. If so, we will again grab the full range of the abbreviation and compare it with the user selection.

When the user selects a bit of text with the abbreviation attribute, along with a bit without it, we do not want to change the command’s value. We will thus use the `containsRange()` method to see if the selected range is within the abbreviation range. The second parameter makes it a `loose` check, meaning the selected range can start, end, or be equal to the abbreviation range.

```
// abbreviation/abbreviationcommand.js

// Previously imported packages.
//...

export default class AbbreviationCommand extends Command {
    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;
        const firstRange = selection.getFirstRange();

        if ( firstRange.isCollapsed ) {
            // When the selection is collapsed, the command has a value
            // if the caret is in an abbreviation.
            // ...
        }
        // When the selection is not collapsed, the command has a value if the selection
        // contains a subset of a single abbreviation or an entire abbreviation.
        else {
            if ( selection.hasAttribute( 'abbreviation' ) ) {
                const attributeValue = selection.getAttribute( 'abbreviation' );

                // Find the entire range containing the abbreviation
                // under the caret position.
                const abbreviationRange = findAttributeRange(
                    selection.getFirstPosition(), 'abbreviation', attributeValue, model
                );

                if ( abbreviationRange.containsRange( firstRange, true ) ) {
                    this.value = {
                        abbr: getRangeText( firstRange ),
                        title: attributeValue,
                        range: firstRange
                    };
                } else {
                    this.value = null;
                }
            } else {
                this.value = null;
            }
        }

        // The code that enables the command.
        // ...
    }

    execute( { title, abbr } ) {
        // The code runs after command execution.
        // ...
    }
}

```

You can check the command and its current value in the inspector.

We can now check the command value when the user presses the toolbar abbreviation button, and insert both abbreviation text and title values into the form’s input fields.

In the `AbbreviationUI` add a simple `if` statement to fill the form using either the value of the command, or the selected text (as we did before).

```
// abbreviation/abbreviationui.js

// Previously imported packages.
// ...

export default class AbbreviationUI extends Plugin {
    // Previously declared methods.
    // ...

    _showUI() {
        const selection = this.editor.model.document.selection;

        // Check the value of the command.
        const commandValue = this.editor.commands.get( 'addAbbreviation' ).value;

        this._balloon.add( {
            view: this.formView,
            position: this._getBalloonPositionData()
        } );

        // Disable the input when the selection is not collapsed.
        this.formView.abbrInputView.isEnabled = selection.getFirstRange().isCollapsed;

        // Fill the form using the state (value) of the command.
        if ( commandValue ) {
            this.formView.abbrInputView.fieldView.value = commandValue.abbr;
            this.formView.titleInputView.fieldView.value = commandValue.title;
        }
        // If the command has no value, put the currently selected text (not collapsed)
        // in the first field and empty the second in that case.
        else {
            const selectedText = getRangeText( selection.getFirstRange() );

            this.formView.abbrInputView.fieldView.value = selectedText;
            this.formView.titleInputView.fieldView.value = '';
        }

        this.formView.focus();
    }

    // Previously declared helper methods.
    // ...
}


```

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--improving-the-execute-method">

#### Improving the `execute()` method

We should now introduce more cases into our `execute()` method. For starters, if the user’s selection is not collapsed, we just need to add the abbreviation attribute to their selection instead of inserting the abbreviation text into the model.

If the selection is not collapsed, we will gather all the ranges that are allowed to use the `abbreviation` model attribute, using the schema’s `getValidRanges()` method. Then we will use the `setAttribute()`, to add the title value to each of the ranges.

If the selection is collapsed, we will keep our `insertContent()` model method from before. Then, we need to use `removeSelectionAttribute` method, to stop adding new content into the abbreviation if the user starts to type.

```
// abbreviation/abbreviationcommand.js

// Previously imported packages.
// ...

export default class AbbreviationCommand extends Command {
    refresh() {
        // The code runs after the command refresh.
        // ...
    }

    execute( { abbr, title } ) {
        const model = this.editor.model;
        const selection = model.document.selection;

        model.change( writer => {
            // If selection is collapsed then update the selected abbreviation
            // or insert a new one at the place of caret.
            if ( selection.isCollapsed ) {
                model.insertContent(
                    writer.createText( abbr, { abbreviation: title } )
                );

                // Remove the "abbreviation" attribute attribute from the selection.
                writer.removeSelectionAttribute( 'abbreviation' );
            } else {
                // If the selection has non-collapsed ranges,
                // change the attribute on nodes inside those ranges
                // omitting nodes where the "abbreviation" attribute is disallowed.
                const ranges = model.schema.getValidRanges(
                    selection.getRanges(), 'abbreviation'
                );

                for ( const range of ranges ) {
                    writer.setAttribute( 'abbreviation', title, range );
                }
            }
        } );
    }
}


```

Now we can use the command’s state to check whether the selection is inside an existing abbreviation. If the command’s value is not `null`, we will grab the whole range, and update its text and title.

We will create a position at the end of the inserted abbreviation, and set a selection there. The [insertContent()](../../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertContent) method returns a range, and we grab its end position to define our `positionAfter`.

```
// abbreviation/abbreviationcommand.js

// Previously imported packages.
// ...

export default class AbbreviationCommand extends Command {
    refresh() {
        // The code runs after the command refresh.
        // ...
    }

    execute( { abbr, title } ) {
        const model = this.editor.model;
        const selection = model.document.selection;

        model.change( writer => {
            // If selection is collapsed then update the selected abbreviation
            // or insert a new one at the place of caret.
            if ( selection.isCollapsed ) {
                // When a collapsed selection is inside text with the "abbreviation" attribute,
                // update its text and title.
                if ( this.value ) {
                    const { end: positionAfter } = model.insertContent(
                        writer.createText( abbr, { abbreviation: title } ),
                        this.value.range
                    );

                    // Put the selection at the end of the inserted abbreviation.
                    writer.setSelection( positionAfter );
                }

                writer.removeSelectionAttribute( 'abbreviation' );
            } else {
                // When the selection has non-collapsed node ranges, change the attribute on nodes inside those ranges
                // omitting nodes where the "abbreviation" attribute is disallowed.
                // ...
            }
        } );
    }
}

```

If the collapsed selection is not inside an existing abbreviation, we will insert a text node with the “abbreviation” attribute in place of the caret.

The user might place the abbreviation inside a text, which already has some other model attributes, like “bold” or “italic.” We should first collect them along with our abbreviation attribute, and use the whole list when inserting the abbreviation into the document. We will use our [toMap](../../../api/module%5Futils%5Ftomap.html#function-toMap) helper function to collect all attributes.

```
// abbreviation/abbreviationcommand.js

// More imports.
// ...
import { toMap } from 'ckeditor5';		// ADDED

export default class AbbreviationCommand extends Command {
    refresh() {
        // The code runs after the command refresh.
        // ...
    }

    execute( { abbr, title } ) {
        const model = this.editor.model;
        const selection = model.document.selection;

        model.change( writer => {
            if ( selection.isCollapsed ) {
                if ( this.value ) {
                    // When a collapsed selection is inside text
                    // with the "abbreviation" attribute, update texts.
                    // ...
                }
                // If the collapsed selection is not in an existing abbreviation,
                // insert a text node with the "abbreviation" attribute
                // in place of the caret.
                // If the abbreviation is empty, don't do anything.
                else if ( abbr !== '' ) {
                    const firstPosition = selection.getFirstPosition();

                    // Collect all attributes of the user selection.
                    const attributes = toMap( selection.getAttributes() );

                    // Put the new attribute to the map of attributes.
                    attributes.set( 'abbreviation', title );

                    // Inject the new text node with the abbreviation text
                    // with all selection attributes.
                    const { end: positionAfter } = model.insertContent(
                        writer.createText( abbr, attributes ), firstPosition
                    );

                    // Put the selection at the end of the inserted abbreviation.
                    writer.setSelection( positionAfter );
                }

                writer.removeSelectionAttribute( 'abbreviation' );
            } else {
                // When the selection has non-collapsed node ranges, change the attribute on nodes inside those ranges
                // omitting nodes where the "abbreviation" attribute is disallowed.
                // ...
            }
        } );
    }
}

```

The command is now done, check how it works by trying all our different cases - selection collapsed, not collapsed, inside an existing abbreviation, etc.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--demo">

### Demo

See the result in action.

<a id="ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html--final-code">

### Final code

If you got lost at any point, this is [the final implementation of the plugin](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/abbreviation-plugin/part-3). You can paste the code from different files into your project, or clone and install the whole thing, and it will run out of the box.

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/commands.html"</a>

## Commands

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--commands-purpose">

### Commands purpose

Now that we have the data conversion sorted out, let’s register a `highlight` command. Commands encapsulate logic that can be executed by other plugins or from the user interface, for example by clicking a button in the editor’s toolbar.

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--registering-a-command">

### Registering a command

Let’s create a new `HighlightCommand` class below the `Highlight` function and add the necessary import in `src/plugin.js`:

```
import { Command } from 'ckeditor5';

class HighlightCommand extends Command {
    refresh() {
        // Handle state.
    }

    execute() {
        // Command logic.
    }
}

```

Then at the bottom of the `Highlight` function, add the following code to register the command:

```
editor.commands.add( 'highlight', new HighlightCommand( editor ) );

```

Our command class has two methods:

* `refresh()`, which handles the state.
* `execute()`, which handles the logic.

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--command-state">

#### Command state

Our plugin only allows text highlighting, so when only an image or table is selected in the editor, we should disable the command. We also want to remove highlighting if the command is called and the selected text is already highlighted.

For this reason, we need a state that indicates whether selections in the editor can be highlighted and whether they are already highlighted.

The command state is managed by the `refresh()` method. This method is called whenever the model is updated, ensuring that the state is refreshed and always up-to-date.

Let’s implement the `refresh()` method to update two command properties:

* `value`, which indicates whether the selection is already highlighted,
* `isEnabled`, which indicates whether highlighting is allowed on the current selection.

```
refresh() {
    const { document, schema } = this.editor.model;

    // Check if selection is already highlighted.
    this.value = document.selection.getAttribute( 'highlight' );

    // Check if command is allowed on current selection.
    this.isEnabled = schema.checkAttributeInSelection( document.selection, 'highlight' );
}

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--command-logic">

#### Command logic

Now that we have the necessary state, we can add logic for updating the model.

Let’s update the `execute()` method like this:

```
execute() {
    const model = this.editor.model;
    const selection = model.document.selection;
    const newValue = !this.value;

    model.change( ( writer ) => {
        if ( !selection.isCollapsed ) {
            const ranges = model.schema.getValidRanges( selection.getRanges(), 'highlight' );

            for ( const range of ranges ) {
                if ( newValue ) {
                    writer.setAttribute( 'highlight', newValue, range );
                } else {
                    writer.removeAttribute( 'highlight', range );
                }
            }
        }

        if ( newValue ) {
            return writer.setSelectionAttribute( 'highlight', true );
        }

        return writer.removeSelectionAttribute( 'highlight' );
    } );
}

```

All changes to the model are made using the [model writer](../../../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html). Its instance is available in the callback passed to the [model.change()](../../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-change) method, so we will use it.

In the callback, we first check if the selection is collapsed. Unlike a standard selection, which can span multiple letters, elements, or even blocks, a collapsed selection has a range of zero, meaning that it starts and ends at the same position. In other words, the collapsed selection is just a caret.

If we are dealing with a standard (not collapsed) selection, we check for all the ranges where the `highlight` attribute can be used, loop over them, and either add or remove this attribute depending on the current state.

If the selection is collapsed, we either add or remove the attribute based on the current state.

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--testing-changes">

#### Testing changes

Let’s test our changes. In the browser, select some of the text in the editor. Then open a console and run the following code:

```
editor.execute( 'highlight' );

```

If everything went well, the text you selected should be highlighted in the editor.

In the CKEditor Inspector, open the `Commands` tab to see all available commands. The `highlight` command should also be listed.

<a id="ckeditor5/latest/framework/tutorials/crash-course/commands.html--whats-next">

### What’s next

If you want to read more about the commands, see the [Commands](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) document.

Otherwise go to the next chapter, where you will [learn more about updating the model UI](#ckeditor5/latest/framework/tutorials/crash-course/view.html).

<a id="ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html"</a>

## Data conversion

<a id="ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html--conversion-helpers">

### Conversion helpers

There are three conversion helpers:

* [attributeToElement()](../../../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-attributeToElement),
* [attributeToAttribute()](../../../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-attributeToAttribute),
* [elementToElement()](../../../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-elementToElement).

We used the first helper in the previous chapter of the tutorial to convert `<mark>` HTML elements to the model’s `highlight` attribute and vice versa.

```
editor.conversion.attributeToElement( {
    model: 'highlight',
    view: 'mark'
} );

```

You may have noticed that we used the term **helpers**. This is because these methods are often used for simple and symmetric conversions, abstracting away the internals and what really happens in the engine. However, there are cases where the conversion is a bit more complicated.

In this chapter we will learn more about data conversion so that you can better understand the editor and work with more complex cases.

<a id="ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html--upcast-and-downcast">

### Upcast and downcast

The process of transforming input HTML data into model is called upcasting. The reverse process of transforming model data into HTML is called downcasting.

While there is only one type of upcast called **data upcast**, there are two types of downcast:

* **data downcast** for converting model data into output HTML data,
* **editing downcast** for converting model into editing view we see in editor UI.

The reason for two types of downcasts is that sometimes the resulting HTML should be different from what we see in the editor. One such example can be a table that in the output HTML data is just a plain HTML table, but in the editing view has additional UI handlers for resizing or buttons for adding new columns and rows. This is a asymmetric conversion for which these helpers are of no use.

<a id="ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html--under-the-hood">

### Under the hood

To better visualize the conversion, let’s see what the above code would look like in a full implementation, without using a helper.

```
// Convert the input `<mark>` HTML element to model attribute.
editor.conversion.for( 'upcast' ).elementToAttribute( {
    model: 'highlight',
    view: 'mark'
} );

// Convert model attribute to output `<mark>` HTML element.
editor.conversion.for( 'dataDowncast' ).attributeToElement( {
    model: 'highlight',
    view: 'mark'
} );

// Convert model attribute to `<mark>` in editing view.
editor.conversion.for( 'editingDowncast' ).attributeToElement( {
    model: 'highlight',
    view: 'mark'
} );

```

Notice that we called the `elementToAttribute` method in the upcast and the `attributeToElement` method in the downcast. This is because in the upcast we convert the HTML element to a model attribute, but in the downcast we do the opposite.

<a id="ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html--whats-next">

### What’s next

If your case requires a more complex conversion than we covered in this tutorial, see the [Conversion deep dive](#ckeditor5/latest/framework/deep-dive/conversion/intro.html) document.

Otherwise, go to the next chapter, where you will [learn more about updating the model using commands](#ckeditor5/latest/framework/tutorials/crash-course/commands.html).

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/editor.html"</a>

## Editor and configuration

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--test-environment">

### Test environment

For this tutorial, we have created a minimal setup required to use the editor. To follow along, run the commands below:

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/crash-course crash-course
cd crash-course

npm install
npm run dev

```

Open the URL displayed in your terminal. If everything went well, you should see a “Hello world!” text displayed on the page.

We encourage you to follow the steps in the tutorial and type the code yourself to build the muscle and mental memory.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--creating-an-editor">

### Creating an editor

The test environment you set up displays the “Hello world!” on the page. Let’s learn the first editor method that replaces this element with the editor.

Open the `src/main.js` file and add the following code:

```
// Import the editor.
import { ClassicEditor } from 'ckeditor5';

// Import the styles.
import 'ckeditor5/ckeditor5.css';

// Get the HTML element with the ID of 'app'.
const element = document.querySelector( '#app' );

// Instantiate the editor using the `create` method.
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL' // Or '<YOUR_LICENSE_KEY>'.
} );

```

As you can see, the [create()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) method creates a new editor instance. It replaces the DOM element passed as the first argument with the editor UI, and sets the initial state of the editor to the content of that DOM element.

However, you may have noticed that the “Hello world!” text does not appear in the editor, and you cannot write anything in it. This may seem strange at first, but it is by design. Let’s fix this with the right configuration.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--configuration">

### Configuration

The editor itself does not do much - it is just an empty shell at this stage. What gives the editor almost all of its functionality are the plugins. We will talk more about plugins in the next chapter, but for now, let’s just install two plugins that provide the bare minimum needed to type in the editor.

```
// Import plugins by adding them to the previously added import.
import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';

// Update the call to the `create()` method.
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    plugins: [
        Essentials,
        Paragraph
    ]
} );

```

As shown in the example above, the [create()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) method takes a configuration object as its second parameter. In this object, we can pass the `plugins` array with the plugins we want to use.

When the page refreshes, you should see the “Hello world!” text in the editor and be able to type in it.

The `Essentials` plugin adds the `Undo` and `Redo` operations. Let’s add them to the editor’s toolbar.

```
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    plugins: [
        Essentials,
        Paragraph
    ],

    // Add the toolbar configuration.
    toolbar: {
        items: [
            'undo',
            'redo'
        ]
    }
} );

```

After refreshing the page, the editor should have two buttons at the top. If you type something into the editor and click the “back arrow” button, your changes should be removed. Clicking the “forward arrow” button should restore those changes.

The configuration object we have just updated controls the features, appearance, and behavior of the editor. If you want to change any aspect of the editor, it is most likely through this object.

The `licenseKey` option is needed for the editor to run. You can learn more about it in the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--editor-methods">

### Editor methods

Now that you can type in the editor, let’s test other editor methods besides `create()`. Add the following to the bottom of the `src/main.js` file. It will allow us to access the editor instance globally for testing purposes.

```
// Add the global `editor` variable (only needed for debugging).
window.editor = editor;

```

Four common methods we will test are:

* [getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData)
* [setData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData)
* [execute()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-execute)
* [destroy()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-destroy)

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--getdata-and-setdata">

#### `getData()` and `setData()`

Open the page in your browser and open the console. Inside the console, run the following code:

```
editor.getData();

```

It should print the text `<p>Hello world!</p>`, which is the current content of the editor. Note the opening and closing `<p>` tags. The`getData()` returns the resulting HTML content of the editor, not the content you see in the UI. This is explained in more detail in the following chapters of the tutorial.

You can also use the `setData()` method to change the content of the editor programmatically.

```
editor.setData( '<p>Modified from the console!</p>' );

```

Running the above command should update the state of the editor. Note the opening and closing `<p>` tags. This method expects HTML as an argument, but the editor displays this content in a more user-friendly way.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--execute">

#### `execute()`

In the previous step of this tutorial, we used the Undo and Redo buttons to revert and restore our changes. Let’s do the same thing from the console.

Before we do that, type something in the editor. Then run the following code from the console:

```
editor.execute( 'undo' );

```

The editor should execute the `undo` command and restore the state to before your changes. Now run the `redo` command to restore those changes:

```
editor.execute( 'redo' );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--destroy">

#### `destroy()`

The `destroy()` method removes the editor and cleans up after it. This includes removing it from the DOM, removing all event listeners, etc.

Run the following command from a console:

```
editor.destroy();

```

The editor and its contents should disappear. **This method returns a promise, so you need to `await` it** if you want to execute more logic after the editor is destroyed.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. But do not install all the dependencies. Instead, run:

```
npm install vite

```

After that, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="app">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/src/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Therefore, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

Also, since the `GPL` key can’t be used for CDN integration, you need to go to our [pricing page](https://ckeditor.com/pricing/) and select a plan that best suits your needs to obtain a license key that can be used in cloud integration. In `src/main.js` set `licenseKey` to your license key.

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/crash-course/editor.html--whats-next">

### What’s next

In the next chapter you will [learn more about plugins](#ckeditor5/latest/framework/tutorials/crash-course/plugins.html) and we will start creating a new one from scratch.

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html"</a>

## Events and observables

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--reactivity">

### Reactivity

In the previous chapter of this tutorial, we wrote the following code to bind selected properties between the button and command objects:

```
button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

```

This line allowed us to make the button reactive and reflect the state of the command. For example, if the command is not allowed to run, the corresponding button should not be clickable.

The reactivity described above is enabled by the [observables](#ckeditor5/latest/framework/deep-dive/observables.html) used in the CKEditor framework. Observables are objects that fire an event when their properties change. These changes can be observed and acted upon, which is exactly what we did with the `highlight` button.

Under the hood, observables use an even more powerful [event system](#ckeditor5/latest/framework/deep-dive/event-system.html) similar to the one in the DOM.

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--observables">

### Observables

Let’s analyze the code we wrote to create the reactive button.

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--creating-an-observable">

#### Creating an observable

Many classes in the editor are already observables. This includes the [Editor](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) class, the [Command](../../../api/module%5Fcore%5Fcommand-Command.html) class, all UI elements that extend the [View](../../../api/module%5Fui%5Fview-View.html) class and many more.

Since the `ButtonView` class is already an observable, we did not have to do anything other than create a new instance.

```
const button = new ButtonView( locale );

```

Then, we called the `.set()` method to update a few button properties.

```
button.set( {
    label: t( 'Highlight' ),
    withText: true,
    tooltip: true,
    isToggleable: true
} );

```

If you want to make a custom class an observable, see the [Observables](#ckeditor5/latest/framework/deep-dive/observables.html) guide.

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--reacting-to-user-input">

#### Reacting to user input

Next, we registered a callback that will be called whenever the `execute` event (bound to the `click` event in the DOM) is fired:

```
button.on( 'execute', () => {
    editor.execute( 'highlight' );
    editor.editing.view.focus();
} );

```

Clicking the button sets the focus on that button, making it impossible for the user to continue typing without clicking the editing view. The `editor.editing.view.focus()` line returns the focus to the editing view, allowing the user to continue typing without interruption.

To learn more about focus, see the [Focus tracking](#ckeditor5/latest/framework/deep-dive/ui/focus-tracking.html) document.

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--binding-properties">

#### Binding properties

Finally, because the button and the command are both observables, we can bind selected properties between them:

```
button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

```

The above line will attach listeners that listen for changes of the `value` and `isEnabled` properties of the command, and update the `isOn` and`isEnabled` button properties accordingly.

This is what the code would look like if you used the event system directly, without using the `bind(...).to(...)` abstraction provided by the observables:

```
command.on( 'change:value', ( event, propName, newValue, oldValue ) => {
    button.isOn = newValue;
} );

command.on( 'change:isEnabled', ( event, propName, newValue, oldValue ) => {
    button.isEnabled = newValue;
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html--whats-next">

### What’s next

If you want to learn more about events and observables, see the [Observables](#ckeditor5/latest/framework/deep-dive/observables.html) and [Event system](#ckeditor5/latest/framework/deep-dive/event-system.html) documents.

Otherwise, go to the next chapter where you will [learn more about handling keystrokes](#ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html), which also uses the CKEditor’s event system.

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html"</a>

## Handling keystrokes

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--accessibility">

### Accessibility

Currently, our `highlight` plugin requires the user to click the button in the editor’s toolbar to highlight selected text. This can be a problem for users who rely on the keyboard, so let’s add a keyboard shortcut as an alternative way to highlight the text.

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--adding-keyboard-shortcuts">

### Adding keyboard shortcuts

A common shortcut for highlighting text is Ctrl \+ Alt \+ H (on Windows systems), so this is what we are going to use in our plugin. On macOS these keystrokes will get automatically translated to Cmd \+ ⌥ \+ H

To execute the `highlight` command when those keys are pressed, add the following code to the end of the `Highlight` function:

```
editor.keystrokes.set( 'Ctrl+Alt+H', 'highlight' );

```

As you can see, the first parameter passed to the function is a string representing the keys that need to be pressed, while the second parameter is the name of the command to be executed. Alternatively, instead of the command name, you can pass a callback and call the command inside:

```
editor.keystrokes.set( 'Ctrl+Alt+H', ( event, cancel ) => {
    editor.execute( 'highlight' );
    cancel();
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--adding-shortcut-information-to-the-accessibility-help-dialog">

### Adding shortcut information to the Accessibility help dialog

The [Accessibility help dialog](#ckeditor5/latest/features/accessibility.html--displaying-keyboard-shortcuts-in-the-editor) displays a complete list of available keyboard shortcuts with their descriptions. It can be opened by pressing Alt \+ 0 (on Windows) or ⌥0 (on macOS). It does not know about the [shortcut we just added](#ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--adding-keyboard-shortcuts), though.

The dialog reads from the [editor.accessibility](../../../api/module%5Fcore%5Faccessibility-Accessibility.html) namespace where all the information about keystrokes and their accessible labels is stored. There is an API to add new entries: ([addKeystrokeInfos](../../../api/module%5Fcore%5Faccessibility-Accessibility.html#function-addKeystrokeInfos), [addKeystrokeInfoGroup](../../../api/module%5Fcore%5Faccessibility-Accessibility.html#function-addKeystrokeInfoGroup), and [addKeystrokeInfoCategory](../../../api/module%5Fcore%5Faccessibility-Accessibility.html#function-addKeystrokeInfoCategory) methods).

In this case, a simple `editor.accessibility.addKeystrokeInfos( ... )` is all you need for the Accessibility help dialog to learn about the new shortcut:

```
const t = editor.t;

editor.accessibility.addKeystrokeInfos( {
    keystrokes: [
        {
            label: t( 'Highlight text' ),
            keystroke: 'Ctrl+Alt+H'
        }
    ]
} );

```

You can learn more about the [AccessibilityHelp](../../../api/module%5Fui%5Feditorui%5Faccessibilityhelp%5Faccessibilityhelp-AccessibilityHelp.html) plugin and the [editor.accessibility](../../../api/module%5Fcore%5Faccessibility-Accessibility.html) namespace in the API reference.

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--updating-button-tooltip">

### Updating button tooltip

When you hover over the “Undo” and “Redo” buttons, you will see a tooltip containing the name of the operation and their respective keyboard shortcuts. However, when hovering over the “Highlight” button, the keyboard shortcut is missing.

We can fix this, by adding the `keystroke` attribute to the button:

```
button.set( {
    label: t( 'Highlight' ),
    withText: true,
    tooltip: true,
    isToggleable: true,
    keystroke: 'Ctrl+Alt+H' // Add this attribute.
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--deep-dive">

### Deep dive

The one-liner we used to register a new keyboard shortcut hides a lot of complexity. Let’s see how we can achieve the same effect using more low-level APIs to better understand what is really happening.

To get the keystrokes, we can listen to the events from the [event system](#ckeditor5/latest/framework/deep-dive/event-system.html) we explored in the previous tutorial chapter fired from the Editing view document.

```
// 5570632 is the code for the 'Ctrl+Alt+H' keyboard shortcut.
editor.editing.view.document.on( 'keydown:5570632', ( event, data ) => {
    // Call the `highlight` command.
    editor.execute( 'highlight' );

    // Stop the event in the DOM.
    data.preventDefault();
    data.stopPropagation();

    // Stop the event in the framework.
    event.stop();

    // Mark this event as handled.
    event.return = true;
} );

```

As you can see above, we registered a listener that listens to the events fired when the Ctrl \+ Alt \+ H keys are pressed. When this happens, the callback is called and it executes the `highlight` command.

To make sure that nothing unexpected happens (for example if some browser extension also uses this keyboard shortcut), we stop further propagation of the event. This prevents any other DOM or framework listeners from reacting to this key combination and marks the event as handled.

<a id="ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html--whats-next">

### What’s next

In the next and final chapter, you will [learn more about plugin configuration](#ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html).

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html"</a>

## Model and schema

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--the-editor">

### The editor

The editors come in a few flavors. While each looks different visually, they are similar under the hood and consist of two parts:

* Editing engine,
* Editing UI.

In this and the next chapters of this tutorial, you will learn about the **editing engine**, which is responsible for reading, maintaining, and outputting the state of the editor, and everything else that powers the editor under the hood.

Later you will also learn about the **editing UI**, but for now, all you need to know is that it is the interface the user sees and interacts with.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--model">

#### Model

The first and most important part of the editing engine is the model. The model is an HTML-like structure that represents the content of the editor. When the [editor.setData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-setData) method is called, HTML passed as the argument is converted into the model. Then, when the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method is called, the model is converted back to HTML.

One major difference between the model and HTML is that in the model, both text and elements can have attributes.

Let’s see how the model compares to HTML.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--schema">

#### Schema

You cannot put anything you want inside the document model. At least not until you update the schema. The schema defines what is allowed and where, what attributes are allowed for certain nodes, what is not allowed, and so on.

Schema determines things like whether the given element can be enclosed in a block quote, or whether the bold button is enabled on selected content.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--extending-the-model-to-support-text-highlighting">

### Extending the model to support text highlighting

With this information, what do we need to do to add support for highlighting? There are two things we need to take care of:

1. We need to somehow track in the model which parts of the text are highlighted.
2. Since HTML has a `<mark>` element used for highlighting, we want to be able to convert it to and from the model.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--extending-the-schema">

#### Extending the schema

As we learned earlier, text nodes in a model can have attributes. We also saw that italic, bold, and underlined text does not use elements like in HTML, but the text attributes. Since highlighting works the same way as those three text styles, let’s follow the same path.

Let’s extend the `$text` node to allow a new attribute called `highlight`. Add the following code to the end of the `Highlight` function in `src/plugin.js`:

```
editor.model.schema.extend( '$text', {
    allowAttributes: 'highlight'
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--converting-the-html-elements">

#### Converting the HTML elements

Now that we can add the `highlight` attribute to the text parts, let’s make it possible to convert `<mark>` HTML elements to the model `highlight` attribute and vice versa. Add the following code to the end of the `Highlight` function in `src/plugin.js`:

```
editor.conversion.attributeToElement( {
    model: 'highlight',
    view: 'mark'
} );

```

Why is the method called `attributeToElement()` when we want to convert `<mark>` HTML **element** to `highlight` model **attribute**? Should it be the other way around?

For the editor, the model is the most important state, and HTML is just input and output. From its perspective, the role is reversed - it has the `highlight` attribute, which corresponds to the`<mark>` element in HTML. You will see this pattern repeated when we dive deeper into data conversion in the next chapter.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--testing-changes">

#### Testing changes

Let’s test our changes. Open the console in your browser and run the following code:

```
editor.setData( '<p>Hello <mark>world</mark>!</p>' );

```

If all went well, the word `world` should be highlighted in the editor.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--ckeditor-inspector">

### CKEditor inspector

Let’s inspect the editor to validate the schema and model. Open the `src/main.js` file and install the [CKEditor inspector](#ckeditor5/latest/framework/develpment-tools/inspector.html).

```
// Import inspector.
import CKEditorInspector from '@ckeditor/ckeditor5-inspector';

// Add this at the bottom of the file to inspect the editor.
CKEditorInspector.attach(editor);

```

When the page refreshes, you should see a debugging panel for CKEditor. Go to the `Schema` tab and click the `$text` element. On the right side you should see `highlight:true` under the `Allowed Attributes` section.

Go to the `Model` tab and re-run this code in the console:

```
editor.setData( '<p>Hello <mark>world</mark>!</p>' );

```

Notice how the model has changed and the `highlight` attribute has been attached to the `"world"` string.

You can also go to the `View` tab to see how the `highlight` attribute is converted to the `<mark>` element.

We will be using this tool in the next stages of plugin development.

<a id="ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html--whats-next">

### What’s next

If you want to read more about the editing engine, see the [Editing engine](#ckeditor5/latest/framework/architecture/editing-engine.html) document.

Otherwise, go to the next chapter, where you will [learn more about data conversion](#ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html) and what really happens when we call the `attributeToElement()` method.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html"</a>

## Plugin configuration

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html--configuration-convention">

### Configuration convention

As we learned at the beginning of this tutorial, the editor accepts a configuration object that allows you to change its default behavior and appearance. The convention used in CKEditor 5 is to have a unique object key for each plugin to avoid conflicts and to make it obvious what each part of the configuration does.

In this tutorial, we will add a single option to the `highlight` plugin to configure its keyboard shortcut. This configuration will be included in an optional `highlight` key:

```
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    // Other options are omitted for readability - do not remove them.
    highlight: {

    }
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html--adding-a-new-configuration-key">

### Adding a new configuration key

Once we know the shape of the configuration object that the plugin will accept, let’s define a new configuration key and default values. These values will be used if the configuration is not provided in the editor configuration.

To do this, add the following code at the top of the `Highlight` function:

```
editor.config.define( 'highlight', {
    keystroke: 'Ctrl+Alt+H'
} );

```

The first parameter passed to the method is the name of the configuration object key, and the second is the default values.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html--loading-configuration-option">

#### Loading configuration option

We have defined the default value for the `keystroke` key as `'Ctrl+Alt+H'`, which is the value we currently have hardcoded into our plugin. Let’s update our plugin to read this value from the configuration instead.

After the configuration we defined above, add the following line to read the `keystroke` configuration:

```
const keystroke = editor.config.get( 'highlight.keystroke' );

```

Then, replace both occurrences of the `'Ctrl+Alt+H'` string in our plugin:

```
button.set( {
    label: t( 'Highlight' ),
    withText: true,
    tooltip: true,
    isToggleable: true,
    keystroke // Update this line.
} );

```

```
editor.keystrokes.set( keystroke, 'highlight' ); // Update this line.

```

```
const t = editor.t;

editor.accessibility.addKeystrokeInfos( {
    keystrokes: [
        {
            label: t( 'Highlight text' ),
            keystroke: keystroke // Update this line.
        }
    ]
} );

```

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html--testing-changes">

#### Testing changes

Let’s test our changes. In the browser, select some of the text in the editor and press the Ctrl \+ Alt \+ H to see if the default configuration works as it did before.

Then, open the `src/main.js` file and update the editor’s configuration to change the highlight keyboard shortcut to Ctrl \+ Alt \+ 9:

```
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    // Other options are omitted for readability - do not remove them.
    highlight: {
        keystroke: 'Ctrl+Alt+9'
    }
} );

```

Finally, in the browser, select some of the text in the editor and press the Ctrl \+ Alt \+ 9 keys to confirm that the new shortcut works.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html--the-end">

### The end?

Congratulations, you have just finished this tutorial!

This is not the end, though. If you want to continue learning, go to the [Framework section](#ckeditor5/latest/framework/index.html) of our documentation.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/plugins.html"</a>

## Plugins

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html--dependencies">

### Dependencies

In the previous chapter of this tutorial, we learned that the editor is just an empty shell, and what gives the editor almost all of its functionality are the plugins. We also installed two plugins to be able to type in the editor.

```
import { Essentials, Paragraph } from 'ckeditor5';

const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    plugins: [
        Essentials,
        Paragraph
    ]
} );

```

However, we have actually installed more plugins - how so?

The `Essentials` plugin is a wrapper for other plugins, each providing the basic functionality you would expect from a text editor:

* [Clipboard](../../../api/module%5Fclipboard%5Fclipboard-Clipboard.html),
* [Enter](../../../api/module%5Fenter%5Fenter-Enter.html),
* [SelectAll](../../../api/module%5Fselect-all%5Fselectall-SelectAll.html),
* [ShiftEnter](../../../api/module%5Fenter%5Fshiftenter-ShiftEnter.html),
* [Typing](../../../api/module%5Ftyping%5Ftyping-Typing.html),
* [Undo](../../../api/module%5Fundo%5Fundo-Undo.html).

Another common pattern is that plugins depend on other plugins and need them to work properly. This is usually noted in the documentation of a given plugin, and the error messages thrown by the editor will include an explanation of what’s missing.

Since the `Essentials` plugin does not define block-level containers, we also installed the `Paragraph` plugin to add support for the `<p>` HTML tag.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html--list-of-plugins">

### List of plugins

The editor we created so far still lacks many features, such as support for headings, tables, block quotes, and much more. You can add them using plugins, of course.

For a list of plugins, usage examples, installation, and configuration options, see the [Plugins and HTML output](#ckeditor5/latest/framework/architecture/plugins.html--plugins-and-html-output) guide.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html--creating-custom-plugins">

### Creating custom plugins

If the editor and any of its plugins do not provide the functionality you need, you may want to create a custom plugin. This requires knowledge of the editor’s internals, which we will discover in the next chapters of the tutorial.

We will create a simplified version of the existing [highlight](#ckeditor5/latest/features/highlight.html) plugin. We want to be able to highlight certain parts of the text to make them stand out from the rest.

If you ever get stuck, want to see an example of writing a TypeScript plugin, or just want to see our APIs in action, check out the [Highlight plugin source code](https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-highlight).

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html--registering-custom-plugin">

#### Registering custom plugin

In the project, we created in the previous chapter, open the `src/plugin.js` file. Inside it, create and export a `Highlight` function.

```
export function Highlight( editor ) {
    console.log( 'Highlight plugin has been registered' );
}

```

Then, in the `src/main.js` file, import and register this function as an editor plugin.

```
import { Highlight } from './plugin';

const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    plugins: [
        // Other plugins are omitted for readability - do not remove them.
        Highlight
    ]
} );

```

Now when the page refreshes, you should see a `Highlight plugin has been registered` text printed in the console. This confirms that the plugin constructor is called correctly.

<a id="ckeditor5/latest/framework/tutorials/crash-course/plugins.html--whats-next">

### What’s next

In the next chapter, you will continue creating a custom plugin and [learn more about model and schema](#ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html), which control the state of the editor.

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html">source file: "ckeditor5/latest/framework/tutorials/crash-course/view.html"</a>

## Editor UI

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html--interface-parts">

### Interface parts

In the previous chapter of this tutorial, we created a command to highlight selected text. However, having to open a console and run a command is cumbersome and definitely not what editor users want.

Let’s update the editor interface to make this easier for them.

The editor interface consists of two parts:

* **toolbar** with buttons, dropdowns and other elements for performing various types of operations,
* **editing view** for typing and modifying content.

In this section, we will focus on updating the toolbar.

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html--creating-a-new-button">

### Creating a new button

Let’s import the `ButtonView` constructor in the `src/plugin.js` file:

```
// Import ButtonView by adding it to the previously added import.
import { Command, ButtonView } from 'ckeditor5';

```

Then add the following code at the bottom of the `Highlight` method:

```
editor.ui.componentFactory.add( 'highlight', ( locale ) => {
    const button = new ButtonView( locale );
    const command = editor.commands.get( 'highlight' );
    const t = editor.t;

    button.set( {
        label: t( 'Highlight' ),
        withText: true,
        tooltip: true,
        isToggleable: true
    } );

    button.on( 'execute', () => {
        editor.execute( 'highlight' );
        editor.editing.view.focus();
    } );

    button.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

    return button;
} );

```

The editor’s UI elements are registered using the `componentFactory`, where the first parameter is the name of the element and the second is the callback that returns that element.

In the callback we do four things:

* Create a [button](../../../api/module%5Fui%5Fbutton%5Fbutton-Button.html) and set a few properties on it, one of which is the translated text created with the [editor.t()](../../../api/module%5Futils%5Flocale-Locale.html#member-t) method.
* Register a callback that will execute the `highlight` command and put the focus back to the editing view when the button is pressed.
* Bind the `isOn` and `isEnabled` button properties to the `value` and `isEnabled` command properties. This ensures that the button is only clickable when the command can be executed, and that it is active when the selection is already highlighted.
* Return the configured button.

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html--registering-a-new-button">

### Registering a new button

When we go back to the browser, we see that nothing has changed. The button we just created is not there.

This is because to see the button, we need to register it in the editor’s configuration. To do this, add the `'highlight'` string (the name we passed as the first argument to the `editor.ui.componentFactory.add()` method) to the `toolbar.items` array.

Open `src/main.js` and update the configuration of the editor:

```
const editor = await ClassicEditor.create( {
    attachTo: element,
    licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
    plugins: [
        Essentials,
        Paragraph,
        Highlight
    ],
    toolbar: {
        items: [
            'undo',
            'redo',
            'highlight' // Add this line.
        ]
    }
} );

```

When you refresh the page, the button should be there.

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html--testing-changes">

#### Testing changes

Let’s test our changes. In the browser, select some text in the editor and click the highlight button in the toolbar.

If all went well, the text you selected should be highlighted in the editor and the button should be active. If you click the button again, the selection should be removed and the button should no longer be active.

<a id="ckeditor5/latest/framework/tutorials/crash-course/view.html--whats-next">

### What’s next

Congratulations, you have just finished this tutorial!

If you want to read more about the editor’s UI, see the [UI library](#ckeditor5/latest/framework/architecture/ui-library.html) document.

Otherwise, go to the next chapter, where you will [learn more about events and observables](#ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html) and better understand the `bind(...).to(...)` mechanism we used to make the button reactive.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html">source file: "ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html"</a>

## Creating a basic plugin

This guide will show you how to create a simple, basic plugin that will let the users insert timestamps into their content. This is a beginner-friendly tutorial, perfect for your first interaction with the CKEditor 5 framework. While it is not necessary to be familiar with the [CKEditor 5 Crash course](#ckeditor5/latest/framework/tutorials/crash-course/editor.html) to follow it, you should consider reading that one, too.

We will create a toolbar button that will insert the current date and time at the caret position into the document. If you want to see the final product of this tutorial before you plunge in, check out the [live demo](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--demo) below.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--lets-start">

### Let’s start!

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/timestamp-plugin/starter-files timestamp-plugin
cd timestamp-plugin

npm install
npm run dev

```

This will create a new directory called `timestamp-plugin` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--creating-a-plugin">

### Creating a plugin

All features in the CKEditor 5 are powered by plugins. To create our custom timestamp plugin, we need to import the base `Plugin` class from the `ckeditor5`. Be careful not to remove the other imports from this package.

```
import {
    // Other imports
    Plugin
} from 'ckeditor5';

```

We can now create a `Timestamp` class that extends the basic `Plugin` class. After we define it, we can add it to the editor’s plugins array.

```
class Timestamp extends Plugin {
    init() {
        console.log( 'Timestamp was initialized.' );
    }
}

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        // Add the Timestamp plugin to config.plugins array.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic, Timestamp
        ]
    } );

```

The development server will refresh. The initialization of the timestamp plugin should be visible. You should see this in the browser (on the left) and the browser’s development console (on the right):

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--registering-a-toolbar-button">

### Registering a toolbar button

CKEditor 5 has a rich UI library. We will grab the `ButtonView` class for our toolbar button from there.

Once we create a new instance of `ButtonView`, we will be able to customize it by setting its properties. We will create a label, which will be visible on the button thanks to the `withText` property.

We also need to register our button in the editor’s UI `componentFactory`, so it can be displayed in the toolbar. To do it, we will pass the name of the button in the `componentFactory.add` method, to be able to add it into the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) array.

```
import {
    // Other imports
    ButtonView
} from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

class Timestamp extends Plugin {
    init() {
        const editor = this.editor;
        // The button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'timestamp', () => {
            // The button will be an instance of ButtonView.
            const button = new ButtonView();

            button.set( {
                label: 'Timestamp',
                withText: true
            } );

            return button;
        } );
    }
}

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic, Timestamp
        ],
        // Add the Timestamp button to the config.toolbar array.
        toolbar: [
            'heading', 'bold', 'italic', 'numberedList', 'bulletedList', 'timestamp'
        ]
    } )
    .then( editor => {
        console.log( 'Editor was initialized', editor );
    } )
    .catch( error => {
        console.error( error.stack );
    } );


```

Now, you should be able to see the Timestamp button. It does not do anything just yet, so let’s change that.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--inserting-a-timestamp">

### Inserting a timestamp

We can now define the core functionality of our plugin – the action that should be executed once our button is clicked.

To insert anything into the document structure, we need to [change the model](#ckeditor5/latest/framework/architecture/editing-engine.html--changing-the-model) using the model’s `change()` method. This way we get access to the model writer.

We will use the `insertContent()` method to insert our timestamp into the document. Inside, we just need to create a new text node with the `writer.createText()` method.

```
class Timestamp extends Plugin {
    init() {
        const editor = this.editor;
        // The button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'timestamp', () => {
            // The button will be an instance of ButtonView.
            const button = new ButtonView();

            button.set( {
                label: 'Timestamp',
                withText: true
            } );

            // Execute a callback function when the button is clicked.
            button.on( 'execute', () => {
                const now = new Date();

                // Change the model using the model writer.
                editor.model.change( writer => {

                    // Insert the text at the user's current position.
                    editor.model.insertContent( writer.createText( now.toString() ) );
                } );
            } );

            return button;
        } );
    }
}

```

Well done! You implemented a CKEditor 5 plugin. You should be able to click and see that it works.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--demo">

### Demo

See the result in action.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--full-code">

### Full code

If you got lost at any point, see [the final implementation of the plugin](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/timestamp-plugin/final-project). You can paste the code from `main.js`, or clone and install the whole thing, and it will run out of the box.

<a id="ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. But do not install the dependencies. Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Therefore, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/index.html">source file: "ckeditor5/latest/framework/tutorials/index.html"</a>

## Tutorials

Whether a newcomer to CKEditor 5 or already a seasoned user – be sure to find something useful in the tutorial section. These easy-to-follow, clear, and informative guides will help you better tailor the CKEditor 5 WYSIWYG editor to your specific needs.

<a id="ckeditor5/latest/framework/tutorials/index.html--crash-course">

### Crash course

If these are your early steps in the CKEditor Ecosystem, feel free to take the crash course and start with the [Editor and configuration](#ckeditor5/latest/framework/tutorials/crash-course/editor.html) tutorial, explaining in detail how things work. The course will further introduce you to [CKEditor 5 plugins and their creation](#ckeditor5/latest/framework/tutorials/crash-course/plugins.html), explain all about [model and schema](#ckeditor5/latest/framework/tutorials/crash-course/model-and-schema.html) and how to extend it. There are also guides to [data conversion](#ckeditor5/latest/framework/tutorials/crash-course/data-conversion.html), the [editor commands](#ckeditor5/latest/framework/tutorials/crash-course/commands.html), and finally [introduction to user interface](#ckeditor5/latest/framework/tutorials/crash-course/view.html) explaining how to handle and expand the editor UI. And if that is not enough yet, you will learn how to handle [events and observables](#ckeditor5/latest/framework/tutorials/crash-course/events-and-observables.html) and [keystrokes](#ckeditor5/latest/framework/tutorials/crash-course/keystrokes.html) and how to [configure plugins](#ckeditor5/latest/framework/tutorials/crash-course/plugin-configuration.html).

<a id="ckeditor5/latest/framework/tutorials/index.html--creating-plugins">

### Creating plugins

Start developing your own features on the go with the [timestamp plugin](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html) tutorial to give you an idea of where to start. Should you want to develop advanced CKEditor 5 plugins, have a look at the Creating Abbreviation Plugin three-step course. It will deep-dive into the internal works of feature plugins. This tutorial will explain in detail the [expanding of the model](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-1.html), [handling user input](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-2.html), and finally [creating commands and expanding the UI](#ckeditor5/latest/framework/tutorials/abbreviation-plugin/abbreviation-plugin-level-3.html).

<a id="ckeditor5/latest/framework/tutorials/index.html--using-widgets">

### Using widgets

Widgets are powerful elements of edited documents and can be used as containers for special content, formatting tools, and for other purposes. Our tutorials will show you how to implement a [block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html), and an [inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html), and how to use a [React component in a widget](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html). The [Data from external source](#ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html) tutorial is yet another approach to extending CKEditor 5 capabilities via an advanced plugin. It is a step-by-step guide through the data input, schema handling, adapting the UI, and injecting the data into editor content.

Keep coming back for new tutorials that will make your CKEditor 5 experience even more satisfactory!

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html">source file: "ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html"</a>

## Data from an external source

In this tutorial, you will learn how to implement a widget that fetches data from an external source and updates all own instances in a set interval of time.

You will build an “external data fetch” feature that allows users to insert a predefined widget that will show the current Bitcoin rate and it will be updated with the set time interval fetching data from a predefined external source. You will use widget utilities and conversion to define the behavior of this feature. Later on, you will use [UI library](#ckeditor5/latest/framework/architecture/ui-library.html) to create a [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) that will allow for inserting new instances of external source widgets. You will also learn how to update the widget data based on the editor API.

If you want to see the final product of this tutorial before you plunge in, check out the [demo](#ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--demo).

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--before-you-start">

### Before you start

This guide assumes that you are familiar with the widgets concept introduced in the [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html) and [Implementing an inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html) tutorials. The tutorial also references various concepts concerning the [CKEditor 5 architecture](#ckeditor5/latest/framework/architecture/intro.html).

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--bootstrapping-the-project">

### Bootstrapping the project

The overall project structure will be similar to one described in the [Bootstrapping the project](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--bootstrapping-the-project) section of the “Implementing an inline widget” tutorial.

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/data-from-external-source/starter-files data-from-external-source
cd data-from-external-source

npm install
npm run dev

```

This will create a new directory called `data-from-external-source` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

First, lets define the `ExternalDataWidget` plugin. The project structure should be as follows:

```
├── main.js
├── index.html
├── node_modules
├── package.json
├── external-data-widget
│   ├── externaldatawidget.js
│   ├── externaldatawidgetcommand.js
│   ├── externaldatawidgetediting.js
│   ├── externaldatawidgetui.js
│   └── theme
│       └── externaldatawidget.css
└── ...

```

You can see that the external data widget feature follows an established plugin structure: the master (glue) plugin (`external-data-widget/externaldatawidget.js`), the “editing” (`external-data-widget/externaldatawidgetediting.js`), and the “UI” (`external-data-widget/externaldatawidgetui.js`) parts.

The master (glue) plugin:

```
// external-data-widget/externaldatawidget.js

import { Plugin } from 'ckeditor5';

import ExternalDataWidgetEditing from './externaldatawidgetediting';
import ExternalDataWidgetUI from './externaldatawidgetui';

export default class ExternalDataWidget extends Plugin {
    static get requires() {
        return [ ExternalDataWidgetEditing, ExternalDataWidgetUI ];
    }
}

```

The UI part (empty for now):

```
// external-data-widget/externaldatawidgetui.js

import { Plugin } from 'ckeditor5';

export default class ExternalDataWidgetUI extends Plugin {
    init() {
        console.log( 'ExternalDataWidgetUI#init() got called' );
    }
}

```

And the editing part (empty for now):

```
// external-data-widget/externaldatawidgetediting.js

import { Plugin } from 'ckeditor5';

export default class ExternalDataWidgetEditing extends Plugin {
    init() {
        console.log( 'ExternalDataWidgetEditing#init() got called' );
    }
}

```

Finally, you need to load the `ExternalDataWidget` plugin in your `main.js` file:

```
// main.js

import ExternalDataWidget from './external-data-widget/externaldatawidget';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, ExternalDataWidget ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'undo', 'redo' ]
    } );

```

At this stage you can run the project and open it in the browser to verify if it is loading correctly.

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--the-model-and-the-view-layers">

### The model and the view layers

The external data widget feature will be [defined as an inline](../../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html) (text-like) element so it will be inserted into other editor blocks that allow text, like `<paragraph>`. The external data widget will also have a `data-resource-url` attribute. This means that the model representation of the external data widget will look like this:

```
<paragraph>
    External value: <externalElement data-resource-url="RESOURCE_URL"></externalElement>.
</paragraph>

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--defining-the-schema">

#### Defining the schema

The schema definition of this widget is almost the same as in the [inline widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--defining-the-schema) tutorial, the only thing that is different is the `allowAttributes`. In our case we want to allow the `'data-resource-url'` attribute.  
Instead of passing all the attributes to the configuration object we can use [generic items](#ckeditor5/latest/framework/deep-dive/schema.html--generic-items) to inherit already predefined options.

You can also use this opportunity to import the theme file (`theme/externaldatawidget.css`).

```
// external-data-widget/externaldatawidgetediting.js

import { Plugin } from 'ckeditor5';

import './theme/externaldatawidget.css';                                           // ADDED

export default class ExternalDataWidgetEditing extends Plugin {
    init() {
        console.log( 'ExternalDataWidgetEditing#init() got called' );

        this._defineSchema();                                                  // ADDED
    }

    _defineSchema() {                                                          // ADDED
        const schema = this.editor.model.schema;

        schema.register( 'externalElement', {
            // Inheriting all from the generic item
            inheritAllFrom: '$inlineObject',

            // The external data widget can have many attributes
            allowAttributes: [ 'data-resource-url' ]
        } );
    }
}

```

Once the schema is defined, you can now define the model-view converters.

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--defining-converters">

#### Defining converters

The HTML structure (data output) of the converter will be a `<span>` with a `data-resource-url` attribute with the external resource URL as its value.

```
<span data-resource-url="RESOURCE_URL"></span>

```

* [**Upcast conversion**](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html). This view-to-model converter will look for `<span>`s with the `data-resource-url` attribute and will create model `<externalElement>` elements with the same `data-resource-url` attribute set accordingly.
* [**Downcast conversion**](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html). The model-to-view conversion will be slightly different for the “editing” and “data” pipelines as the “editing downcast” pipeline will use widget utilities to enable widget-specific behavior in the editing view. In both pipelines, the element will be rendered using the same structure.

```
// external-data-widget/externaldatawidgetediting.js

// ADDED 2 imports
import { Plugin, Widget, toWidget } from 'ckeditor5';

import './theme/externaldatawidget.css';

export default class ExternalDataWidgetEditing extends Plugin {
    static get requires() {                                                    // ADDED
        return [ Widget ];
    }

    init() {
        console.log( 'ExternalDataWidgetEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();                                              // ADDED
    }

    _defineSchema() {                                                          // ADDED
        // Previously registered schema.
        // ...
    }

    _defineConverters() {                                                      // ADDED
        const editor = this.editor;

        editor.conversion.for( 'upcast' ).elementToElement( {
            view: {
                name: 'span',
                attributes: [ 'data-resource-url' ]
            },
            model: ( viewElement, { writer } ) => {
                const externalUrl = viewElement.getAttribute( 'data-resource-url' );

                return writer.createElement( 'externalElement', {
                    'data-resource-url': externalUrl
                } );
            }
        } );

        editor.conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'externalElement',
            view: ( modelElement, { writer } ) => {
                return writer.createEmptyElement( 'span', {
                    'data-resource-url': modelElement.getAttribute( 'data-resource-url' )
                } );
            }
        } );

        editor.conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'externalElement',
            view: ( modelElement, { writer } ) => {
                const externalDataPreviewElement = writer.createRawElement( 'span', null, function( domElement ) {
                    // For now show some static text
                    domElement.textContent = 'Data placeholder';
                } );

                const externalWidgetContainer = writer.createContainerElement( 'span', null, externalDataPreviewElement );

                return toWidget( externalWidgetContainer, writer, {
                    label: 'External widget'
                } );
            }
        } );
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--feature-styles">

#### Feature styles

As you might have noticed, the editing part imports the `./theme/externaldatawidget.css` CSS file which describes how the widget will look like and how it will be animated when a new value arrives:

```
/* external-data-widget/theme/externaldatawidget.css */

.external-data-widget {
    border: 2px solid rgb(242, 169, 0);
}

.external-data-widget-bounce {
    animation: external-data-widget-bounce-animation 1.5s 1;
}

@keyframes external-data-widget-bounce-animation {
    0% {
        box-shadow: 0px 0px 0px 0px rgba(242, 169, 0, 1);
    }

    100% {
        box-shadow: 0px 0px 0px 10px rgba(242, 169, 0, 0);
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--the-command">

#### The command

The [command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) for the external data widget feature will insert an `<externalElement>` element (if allowed by the schema) at the selection and set the selection on the inserted widget.

```
// external-data-widget/externaldatawidgetcommand.js

import { Command } from 'ckeditor5';

// example external data source url
const RESOURCE_URL = 'https://api2.binance.com/api/v3/ticker/24hr?symbol=BTCUSDT';

class ExternalDataWidgetCommand extends Command {
    execute() {
        const editor = this.editor;
        const selection = editor.model.document.selection;

        editor.model.change( writer => {
            // Create an <externalElement> element with the "data-resource-url" attribute
            // (and all the selection attributes)...
            const externalWidget = writer.createElement(
                'externalElement', {
                    ...Object.fromEntries( selection.getAttributes() ),
                    'data-resource-url': RESOURCE_URL
                }
            );

            // ... insert it into the document and put the selection on the inserted element.
            editor.model.insertObject( externalWidget, null, null, {
                setSelection: 'on'
            } );
        } );
    }

    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;

        const isAllowed = model.schema.checkChild( selection.focus.parent, 'externalElement' );

        this.isEnabled = isAllowed;
    }
}

```

Import the newly created command and add it to the editor commands:

```
// external-data-widget/externaldatawidgetediting.js

import { Plugin, Widget, toWidget } from 'ckeditor5';

import ExternalDataWidgetCommand from './externaldatawidgetcommand';                   // ADDED
import './theme/externaldatawidget.css';

export default class ExternalDataWidgetEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'ExternalDataWidgetEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        // ADDED
        this.editor.commands.add( 'external', new ExternalDataWidgetCommand( this.editor ) );
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--creating-the-ui">

### Creating the UI

The UI part provides a [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) that users can click to insert the external data widget into the editor.

Register and configure the toolbar button as shown below. The icon of the button can be found among official [Bitcoin promotional graphics](https://en.bitcoin.it/wiki/Promotional%5Fgraphics). Put the SVG file in the `./theme` directory and import it next to the UI plugin so it can be used by the button.

```
// external-data-widget/externaldatawidgetui.js

import { Plugin, ButtonView } from 'ckeditor5';

import BitcoinLogoIcon from './theme/bitcoin-logo.svg';

class ExternalDataWidgetUI extends Plugin {
    init() {
        const editor = this.editor;
        const externalWidgetCommand = editor.commands.get( 'external' );

        // The "external" button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'external', locale => {
            const button = new ButtonView( locale );

            button.set( {
                label: 'Bitcoin rate',
                tooltip: true,
                withText: false,
                icon: BitcoinLogoIcon
            } );

            // Disable the external data widget button when the command is disabled.
            button.bind( 'isEnabled' ).to( externalWidgetCommand );

            // Execute the command when the button is clicked (executed).
            button.on( 'execute', () => {
                editor.execute( 'external' );
                // Set focus on the editor content
                editor.editing.view.focus();
            } );

            return button;
        } );
    }
}

```

Add the [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) to the toolbar:

```
// main.js

import {
    ClassicEditor,
    Bold,
    Italic,
    Essentials,
    Heading,
    List,
    Paragraph
} from 'ckeditor5';

import ExternalDataWidgetCommand from './externaldatawidgetcommand';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, ExternalDataWidget ],

        // Insert the "external" button into the editor toolbar.
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'external', '|', 'undo', 'redo' ]
    } )
    .then( editor => {
        console.log( 'Editor was initialized', editor );

        // Expose for playing in the console.
        window.editor = editor;
    } )
    .catch( error => {
        console.error( error.stack );
    } );

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--handling-the-external-source">

### Handling the external source

In this tutorial we will use an external API that provides a current Bitcoin rate (in USD). This endpoint does not need any API keys and it is free to use but it has some [limitations](https://binance-docs.github.io/apidocs/spot/en/#limits).

```
'https://api2.binance.com/api/v3/ticker/24hr?symbol=BTCUSDT'

```

The data will be fetched every 10 seconds. Each instance of the widget will be updated at the same time. To achieve that, we need to modify the `ExternalDataWidgetEditing` class.

```
class ExternalDataWidgetEditing extends Plugin {
    //
    constructor( editor ) {
        // The default constructor calls the parent constructor
        super( editor );
        // Property that keep the interval id
        this.intervalId = this._intervalFetch();
        // Last fetched value
        this.externalDataValue = '';
    }

    static get requires() {
        return [ Widget ];
    }

    // This method will help us to clear the interval
    destroy() {
        clearInterval( this.intervalId );
    }

    init() {
        this._defineSchema();
        this._defineConverters();
        // Initial execute function to fetch and update the data
        this._updateWidgetData();

        this.editor.commands.add( 'external', new ExternalDataWidgetCommand( this.editor ) );
    }

    // Interval function
    _intervalFetch() {
        return setInterval( () => this._updateWidgetData(), 10000 ); // set time interval to 10s
    }

    // Fetch data and update all widget instances
    async _updateWidgetData( externalUrl = RESOURCE_URL ) {
        try {
            const response = await fetch( externalUrl );
            const data = await response.json();
            const updateTime = new Date( data.closeTime );

            // Example parsed data: $17098.35 - 09/11/2022, 18:04:18
            const parsedData = `$${Number(data.lastPrice).toFixed(2)} - ${updateTime.toLocaleString()}`;

            // Update property with last fetched and parsed data
            this.externalDataValue = parsedData;

            const rootElement = this.editor.model.document.getRoot();

            // Iterate over whole editor content, search for external data widget instances
            // and trigger `recovertItem` function
            for ( const { item } of this.editor.model.createRangeIn( rootElement ) ) {
                if ( item.is( 'element', 'externalElement' ) ) {
                    this.editor.editing.reconvertItem( item );
                }
            }
        } catch ( error ) {
            console.error( error );
        }
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined upcast and data downcast converters.
        // ...

        editor.conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'externalElement',
            view: ( modelElement, { writer } ) => {
                const externalValueToShow = this.externalDataValue;

                const externalDataPreviewElement = writer.createRawElement( 'span', null, function( domElement ) {
                    // CSS class responsible for the appearance of the widget
                    domElement.classList.add( 'external-data-widget' );
                    // When the value is not present (initial run) show a placeholder
                    domElement.textContent = externalValueToShow || 'Fetching data...';

                    // If a new value arrives, add a CSS animation effect to show that data were updated
                    if ( externalValueToShow ) {
                        domElement.classList.add( 'external-data-widget-bounce' );
                        // Remove the animation class when it ends
                        setTimeout( () => domElement.classList.remove( 'external-data-widget-bounce' ), 1100 );
                    }
                } );

                const externalWidgetContainer = writer.createContainerElement( 'span', null, externalDataPreviewElement );

                return toWidget( externalWidgetContainer, writer, {
                    label: 'External widget'
                } );
            }
        } );
    }
}


```

The editor content traversal can be a challenging process. The presented method is sufficient when there is relatively little content. Otherwise, a `WeakMap` will be a better option.

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--demo">

### Demo

You can see the external data widget implementation in action in the editor below.

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--final-solution">

### Final solution

If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/data-from-external-source/final-project) available.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/data-from-external-source/final-project final-project
cd final-project

npm install
npm run dev

```

<a id="ckeditor5/latest/framework/tutorials/widgets/data-from-external-source.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. But do not install the dependencies. Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Consequently, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html">source file: "ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html"</a>

## Implementing a block widget

In this tutorial, you will learn how to implement a more complex CKEditor 5 plugin.

You will build a “Simple box” feature, which will allow the user to insert a custom box with a title and body fields into the document. You will utilize the widget utilities and work with the model-view conversion to program the behavior of this feature properly. Later, you will create a UI that inserts new simple boxes into the document using the toolbar button.

If you want to see the final product of this tutorial before you plunge in, check out the [demo](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--demo).

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--before-you-start">

### Before you start

This tutorial will reference various parts of the [CKEditor 5 architecture](#ckeditor5/latest/framework/architecture/intro.html) section as you go. While reading them is not necessary to finish this tutorial, it is recommended to read these guides at some point to get a better understanding of the mechanisms used in this tutorial.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--lets-start">

### Let’s start

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/block-widget/starter-files block-widget
cd block-widget

npm install
npm run dev

```

It will create a new directory called `block-widget` with the necessary files. The `npm install` command will install all dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

Open the URL displayed in your terminal. If everything went well, you should see a CKEditor 5 instance in your browser like this:

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--plugin-structure">

### Plugin structure

Once the editor is up and running, you can start implementing the plugin. You can keep the entire plugin code in a single file; however, it is recommended to split its “editing” and “UI” layers and create a master plugin that loads both. This way, you ensure better separation of concerns and allow for recomposing the features (for example, picking the editing part of an existing feature but writing your own UI for it). All official CKEditor 5 plugins follow this pattern.

Additionally, you will split the code of commands, buttons, and other “self-contained” components into separate files, too. In order not to mix up these files with your project’s `main.js` file, create this directory structure:

```
├── main.js
├── index.html
├── node_modules
├── package.json
├── simplebox
│   ├── simplebox.js
│   ├── simpleboxediting.js
│   └── simpleboxui.js
└─ ...

```

Now define the three plugins.

First, the master (glue) plugin. Its role is to simply load the “editing” and “UI” parts.

```
// simplebox/simplebox.js

import SimpleBoxEditing from './simpleboxediting';
import SimpleBoxUI from './simpleboxui';
import { Plugin } from 'ckeditor5';

export default class SimpleBox extends Plugin {
    static get requires() {
        return [ SimpleBoxEditing, SimpleBoxUI ];
    }
}

```

Now, the remaining two plugins:

```
// simplebox/simpleboxui.js

import { Plugin } from 'ckeditor5';

export default class SimpleBoxUI extends Plugin {
    init() {
        console.log( 'SimpleBoxUI#init() got called' );
    }
}

```

```
// simplebox/simpleboxediting.js

import { Plugin } from 'ckeditor5';

export default class SimpleBoxEditing extends Plugin {
    init() {
        console.log( 'SimpleBoxEditing#init() got called' );
    }
}

```

Finally, you need to load the `SimpleBox` plugin in your `main.js` file:

```
// main.js

import SimpleBox from './simplebox/simplebox';                                 // ADDED

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic,
            SimpleBox                                                          // ADDED
        ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ]
    } );

```

Your page will refresh, and you should see that the editor loaded the `SimpleBoxEditing` and `SimpleBoxUI` plugins:

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--the-model-and-the-view-layers">

### The model and the view layers

CKEditor 5 implements an MVC architecture and its custom data model, while still being a tree structure, does not map to the DOM 1:1\. You can think about the model as an even more semantic representation of the editor content, while the DOM is one of its possible representations.

Since your simple box feature is meant to be a box with a title and description fields, define its model representation like this:

```
<simpleBox>
    <simpleBoxTitle></simpleBoxTitle>
    <simpleBoxDescription></simpleBoxDescription>
</simpleBox>

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--defining-the-schema">

#### Defining the schema

You need to start by defining the model’s schema. You need to describe three elements and their types, as well as the allowed parent and children.

Update the `SimpleBoxEditing` plugin with this definition.

```
// simplebox/simpleboxediting.js

import { Plugin } from 'ckeditor5';

export default class SimpleBoxEditing extends Plugin {
    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();                                                  // ADDED
    }

    _defineSchema() {                                                          // ADDED
        const schema = this.editor.model.schema;

        schema.register( 'simpleBox', {
            // Behaves like a self-contained block object (e.g. a block image)
            // allowed in places where other blocks are allowed (e.g. directly in the root).
            inheritAllFrom: '$blockObject'
        } );

        schema.register( 'simpleBoxTitle', {
            // Cannot be split or left by the caret.
            isLimit: true,

            allowIn: 'simpleBox',

            // Allow content which is allowed in blocks (i.e. text with attributes).
            allowContentOf: '$block'
        } );

        schema.register( 'simpleBoxDescription', {
            // Cannot be split or left by the caret.
            isLimit: true,

            allowIn: 'simpleBox',

            // Allow content which is allowed in the root (e.g. paragraphs).
            allowContentOf: '$root'
        } );
    }
}

```

Defining the schema will not affect the editor, yet. It is the information used by plugins and the editor engine to understand how actions such as pressing the Enter key, clicking an element, typing text, inserting an image, etc., should behave.

For the simple box plugin to start doing anything, you need to define model-view converters. Do that now!

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--defining-converters">

#### Defining converters

Converters inform the editor how to convert the view to the model (for example, when loading data to the editor or handling pasted content) and how to render the model to the view (for editing purposes, or when retrieving the editor data).

It is the moment when you need to think about how you want to render the `<simpleBox>` element and its children to the DOM (what the user will see) and to the data. CKEditor 5 allows converting the model to a different structure for editing purposes and a different one to be stored as “data” or exchanged with other applications when copying and pasting the content. However, for simplicity, use the identical representation in both pipelines for now.

The structure in the view that you want to achieve:

```
<section class="simple-box">
    <h1 class="simple-box-title"></h1>
    <div class="simple-box-description"></div>
</section>

```

Use the [conversion.elementToElement()](../../../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-elementToElement) method to define all the converters.

You need to define converters for three model elements. Update the `SimpleBoxEditing` plugin with this code:

```
// simplebox/simpleboxediting.js

import { Plugin } from 'ckeditor5';

export default class SimpleBoxEditing extends Plugin {
    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();                                              // ADDED
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {                                                      // ADDED
        const conversion = this.editor.conversion;

        conversion.elementToElement( {
            model: 'simpleBox',
            view: {
                name: 'section',
                classes: 'simple-box'
            }
        } );

        conversion.elementToElement( {
            model: 'simpleBoxTitle',
            view: {
                name: 'h1',
                classes: 'simple-box-title'
            }
        } );

        conversion.elementToElement( {
            model: 'simpleBoxDescription',
            view: {
                name: 'div',
                classes: 'simple-box-description'
            }
        } );
    }
}

```

Once you have the converters, you can try to see the simple box in action. You have not defined a way to insert a new simple box into the document yet, so load it via the editor data. To do that, you need to modify the `index.html` file:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 Framework – Implementing a simple widget</title>

        <style>
            .simple-box {
                padding: 10px;
                margin: 1em 0;

                background: rgba( 0, 0, 0, 0.1 );
                border: solid 1px hsl(0, 0%, 77%);
                border-radius: 2px;
            }

            .simple-box-title, .simple-box-description {
                padding: 10px;
                margin: 0;

                background: #FFF;
                border: solid 1px hsl(0, 0%, 77%);
            }

            .simple-box-title {
                margin-bottom: 10px;
            }
        </style>
    </head>
    <body>
        <div id="editor">
            <p>This is a simple box:</p>

            <section class="simple-box">
                <h1 class="simple-box-title">Box title</h1>
                <div class="simple-box-description">
                    <p>The description goes here.</p>
                    <ul>
                        <li>It can contain lists,</li>
                        <li>and other block elements like headings.</li>
                    </ul>
                </div>
            </section>
        </div>

        <script type="module" src="./main.js"></script>
    </body>
</html>

```

Voilà – this is your first simple box instance:

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--what-is-in-the-model">

#### What is in the model?

The HTML that you added to the `index.html` file is your editor’s data. It is what `editor.getData()` would return. Also, for now, this is also the DOM structure that the CKEditor 5 engine renders in the editable region:

However, what’s in the model? To learn that, use the official [CKEditor 5 inspector](#ckeditor5/latest/framework/develpment-tools/inspector.html). Once [installed](#ckeditor5/latest/framework/develpment-tools/inspector.html--importing-the-inspector), you need to load it in the `main.js` file:

```
// main.js

import SimpleBox from './simplebox/simplebox';

import CKEditorInspector from '@ckeditor/ckeditor5-inspector';                 // ADDED

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic,
            SimpleBox
        ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList' ]
    } )
    .then( editor => {
        console.log( 'Editor was initialized', editor );

        CKEditorInspector.attach( { 'editor': editor } );

        window.editor = editor;
    } );

```

After refreshing the page, you will see the inspector:

You will see the following HTML-like string:

```
<paragraph>[]This is a simple box:</paragraph>
<simpleBox>
    <simpleBoxTitle>Box title</simpleBoxTitle>
    <simpleBoxDescription>
        <paragraph>The description goes here.</paragraph>
        <listItem listIndent="0" listType="bulleted">It can contain lists,</listItem>
        <listItem listIndent="0" listType="bulleted">and other block elements like headings.</listItem>
    </simpleBoxDescription>
</simpleBox>

```

As you can see, this structure is quite different than the HTML input/output. If you look closely, you will also notice the `[]` characters in the first paragraph – this is the selection position.

Play with the editor features a bit (bold, italic, headings, lists, selection) to see the changes in the model structure.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--behavior-before-turning-simple-box-into-a-widget">

#### Behavior before turning simple box into a widget

It is time to check if the simple box behaves like you would like it to. You can observe the following:

* You can type text in the title. Pressing Enter will not split it, and Backspace will not delete it entirely. It is because it was marked as an `isLimit` element in the schema.
* You cannot apply a list in the title and cannot turn it into a heading (other than `<h1 class="simple-box-title">`, which it is already). It is because it allows only the content that is allowed in other block elements (like paragraphs). You can, however, apply italic inside the title (because italic is permitted in different blocks).
* The description behaves similarly to the title, but it allows more content inside – lists and other headings.
* If you try to select the entire simple box instance and press Delete, it will be deleted as a whole. The same when you copy and paste it. It is because it was marked as an `isObject` element in the schema.
* You cannot easily select the entire simple box instance by clicking it. Also, the cursor pointer does not change when you hover it. In other words, it seems a bit unresponsive. The reason is that you have not yet defined the view behavior.

Pretty cool so far, right? With little code, you were able to define the behavior of your simple box plugin, which maintains the integrity of these elements. The engine ensures that the user does not break these instances.

See what else you can improve.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--making-simple-box-a-widget">

#### Making simple box a widget

The converters that you defined convert the model `<simpleBox*>` elements to plain [ContainerElement](../../../api/module%5Fengine%5Fview%5Fcontainerelement-ViewContainerElement.html)s in the view (and back during upcasting).

You want to change this behavior a bit so the structure created in the editing view is enhanced with the [toWidget()](../../../api/module%5Fwidget%5Futils.html#function-toWidget) and [toWidgetEditable()](../../../api/module%5Fwidget%5Futils.html#function-toWidgetEditable) utilities. You do not want to affect the data view, though. Therefore, you will need to define converters for the editing and data downcasting separately.

If you find the concept of downcasting and upcasting confusing, read the [introduction to conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion).

Now it is time to revisit the `_defineConverters()` method that you defined earlier. You will use the [elementToElement() upcast helper](../../../api/module%5Fengine%5Fconversion%5Fupcasthelpers-UpcastHelpers.html#function-elementToElement) and the [elementToElement() downcast helper](../../../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-elementToElement) instead of the two-way `elementToElement()` converter helper.

Additionally, ensure that the [Widget](../../../api/module%5Fwidget%5Fwidget-Widget.html) plugin is loaded. If you omit it, the elements in the view will have all the classes (like `ck-widget`), but there will be no “behaviors” loaded (for example, clicking a widget will not select it).

```
// simplebox/simpleboxediting.js

// ADDED 2 imports.
import { Plugin, Widget, toWidget, toWidgetEditable } from 'ckeditor5';

export default class SimpleBoxEditing extends Plugin {
    static get requires() {                                                    // ADDED
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {                                                      // MODIFIED
        const conversion = this.editor.conversion;

        // <simpleBox> converters.
        conversion.for( 'upcast' ).elementToElement( {
            model: 'simpleBox',
            view: {
                name: 'section',
                classes: 'simple-box'
            }
        } );
        conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'simpleBox',
            view: {
                name: 'section',
                classes: 'simple-box'
            }
        } );
        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'simpleBox',
            view: ( modelElement, { writer: viewWriter } ) => {
                const section = viewWriter.createContainerElement( 'section', { class: 'simple-box' } );

                return toWidget( section, viewWriter, { label: 'simple box widget' } );
            }
        } );

        // <simpleBoxTitle> converters.
        conversion.for( 'upcast' ).elementToElement( {
            model: 'simpleBoxTitle',
            view: {
                name: 'h1',
                classes: 'simple-box-title'
            }
        } );
        conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'simpleBoxTitle',
            view: {
                name: 'h1',
                classes: 'simple-box-title'
            }
        } );
        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'simpleBoxTitle',
            view: ( modelElement, { writer: viewWriter } ) => {
                // Note: You use a more specialized createEditableElement() method here.
                const h1 = viewWriter.createEditableElement( 'h1', { class: 'simple-box-title' } );

                return toWidgetEditable( h1, viewWriter );
            }
        } );

        // <simpleBoxDescription> converters.
        conversion.for( 'upcast' ).elementToElement( {
            model: 'simpleBoxDescription',
            view: {
                name: 'div',
                classes: 'simple-box-description'
            }
        } );
        conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'simpleBoxDescription',
            view: {
                name: 'div',
                classes: 'simple-box-description'
            }
        } );
        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'simpleBoxDescription',
            view: ( modelElement, { writer: viewWriter } ) => {
                // Note: You use a more specialized createEditableElement() method here.
                const div = viewWriter.createEditableElement( 'div', { class: 'simple-box-description' } );

                return toWidgetEditable( div, viewWriter );
            }
        } );
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--behavior-after-turning-simple-box-into-a-widget">

#### Behavior after turning simple box into a widget

Now, you should see how your simple box plugin has changed.

You should observe that:

* The `<section>`, `<h1>`, and `<div>` elements have the `contentEditable` attribute on them (plus some classes). This attribute tells the browser whether an element is considered editable. Passing the element through `toWidget()` will make its content non-editable. Conversely, passing it through `toWidgetEditable()` will make its content editable again.
* You can now click the widget (the gray area) to select it. Once the widget is selected, it is easier to copy and paste.
* The widget and its nested editable regions react to hovering, selection, and focus (outline).

In other words, the simple box instance became much more responsive.

Additionally, if you call `editor.getData()`, you will get the same HTML as before the simple box became a widget. It is thanks to using `toWidget()` and `toNestedEditable()` only in the `editingDowncast` pipeline.

This is all you need from the model and the view layers for now. In terms of being editable and data input/output, it is fully functional. Now find a way to insert new simple boxes into the document!

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-a-command">

### Creating a command

A [command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) is a combination of an action and a state. You can interact with most of the editor features by the commands they expose. This allows not only for executing these features (like making a fragment of text bold) but also checking if this action can be executed in the selection’s current location as well as observing other state properties (such as whether the currently selected text was made bold).

For a simple box, the situation is simple:

* You need an “insert a new simple box” action.
* You need a “can you insert a new simple box here (at the current selection position)” check.

Create a new file `insertsimpleboxcommand.js` in the `simplebox/` directory. You will use the [model.insertObject()](../../../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-insertObject) method, which will be able to, for example, split a paragraph if you try to insert a simple box in the middle of it (which is not allowed by the schema).

```
// simplebox/insertsimpleboxcommand.js

import { Command } from 'ckeditor5';

export default class InsertSimpleBoxCommand extends Command {
    execute() {
        this.editor.model.change( writer => {
            // Insert <simpleBox>*</simpleBox> at the current selection position
            // in a way that will result in creating a valid model structure.
            this.editor.model.insertObject( createSimpleBox( writer ) );
        } );
    }

    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;
        const allowedIn = model.schema.findAllowedParent( selection.getFirstPosition(), 'simpleBox' );

        this.isEnabled = allowedIn !== null;
    }
}

function createSimpleBox( writer ) {
    const simpleBox = writer.createElement( 'simpleBox' );
    const simpleBoxTitle = writer.createElement( 'simpleBoxTitle' );
    const simpleBoxDescription = writer.createElement( 'simpleBoxDescription' );

    writer.append( simpleBoxTitle, simpleBox );
    writer.append( simpleBoxDescription, simpleBox );

    // There must be at least one paragraph for the description to be editable.
    // See https://github.com/ckeditor/ckeditor5/issues/1464.
    writer.appendElement( 'paragraph', simpleBoxDescription );

    return simpleBox;
}

```

Import the command and register it in the `SimpleBoxEditing` plugin:

```
// simplebox/simpleboxediting.js

import { Plugin, Widget, toWidget, toWidgetEditable } from 'ckeditor5';

import InsertSimpleBoxCommand from './insertsimpleboxcommand';                 // ADDED

export default class SimpleBoxEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        // ADDED
        this.editor.commands.add( 'insertSimpleBox', new InsertSimpleBoxCommand( this.editor ) );
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

You can now execute this command to insert a new simple box. Call:

```
editor.execute( 'insertSimpleBox' );

```

It should result in:

You can also try inspecting the `isEnabled` property value (or just checking it in the CKEditor 5 inspector):

```
console.log( editor.commands.get( 'insertSimpleBox' ).isEnabled );

```

It is always `true` except when the selection is in one place, in another simple box’s title. You can also observe that executing the command when the selection is in that place takes no effect.

Change one more thing before you move forward – disallow `simpleBox` inside `simpleBoxDescription`, too. This can be done by [defining a custom child check](../../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-addChildCheck):

```
// simplebox/simpleboxediting.js

// Previously imported packages.
// ...

export default class SimpleBoxEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'insertSimpleBox', new InsertSimpleBoxCommand( this.editor ) );
    }

    _defineSchema() {
        const schema = this.editor.model.schema;

        schema.register( 'simpleBox', {
            // Behaves like a self-contained block object (e.g. a block image)
            // allowed in places where other blocks are allowed (e.g. directly in the root).
            inheritAllFrom: '$blockObject'
        } );

        schema.register( 'simpleBoxTitle', {
            // Cannot be split or left by the caret.
            isLimit: true,

            allowIn: 'simpleBox',

            // Allow content which is allowed in blocks (i.e. text with attributes).
            allowContentOf: '$block'
        } );

        schema.register( 'simpleBoxDescription', {
            // Cannot be split or left by the caret.
            isLimit: true,

            allowIn: 'simpleBox',

            // Allow content which is allowed in the root (e.g. paragraphs).
            allowContentOf: '$root'
        } );

        // ADDED
        schema.addChildCheck( ( context, childDefinition ) => {
            if ( context.endsWith( 'simpleBoxDescription' ) && childDefinition.name == 'simpleBox' ) {
                return false;
            }
        } );
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

Now the command should also be disabled when the selection is inside the description of another simple box instance.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-a-button">

### Creating a button

It is time to allow the editor users to insert the widget into the content. The best way to do that is through a UI button in the toolbar. You can quickly create one using the [ButtonView](../../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html) class brought by the [UI framework](#ckeditor5/latest/framework/architecture/ui-library.html) of CKEditor 5.

The button should execute the [command](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-a-command) when clicked and become inactive if the widget cannot be inserted into some particular position of the selection ([as defined in the schema](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--defining-the-schema)).

See what it looks like in practice and extend the `SimpleBoxUI` plugin [created earlier](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--plugin-structure):

```
// simplebox/simpleboxui.js

import { ButtonView, Plugin } from 'ckeditor5';

export default class SimpleBoxUI extends Plugin {
    init() {
        console.log( 'SimpleBoxUI#init() got called' );

        const editor = this.editor;
        const t = editor.t;

        // The "simpleBox" button must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'simpleBox', locale => {
            // The state of the button will be bound to the widget command.
            const command = editor.commands.get( 'insertSimpleBox' );

            // The button will be an instance of ButtonView.
            const buttonView = new ButtonView( locale );

            buttonView.set( {
                // The t() function helps localize the editor. All strings enclosed in t() can be
                // translated and change when the language of the editor changes.
                label: t( 'Simple Box' ),
                withText: true,
                tooltip: true
            } );

            // Bind the state of the button to the command.
            buttonView.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

            // Execute the command when the button is clicked (executed).
            this.listenTo( buttonView, 'execute', () => editor.execute( 'insertSimpleBox' ) );

            return buttonView;
        } );
    }
}

```

The last thing you need to do is tell the editor to display the button in the toolbar. To do that, you will need to slightly modify the code that runs the editor instance and include the button in the [toolbar configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar):

```
ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, SimpleBox ],
        // Insert the "simpleBox" button into the editor toolbar.
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', 'simpleBox' ]
    } )
    .then( editor => {
        // This code runs after the editor initialization.
        // ...
    } )
    .catch( error => {
        // Error handling if something goes wrong during initialization.
        // ...
    } );

```

Refresh the web page and try it yourself:

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--adding-a-widget-toolbar">

### Adding a widget toolbar

So far, you have created a simple box widget with a button to insert it into the editor. But what if you want to add some controls to the widget itself? For example, you might want to allow users to toggle some widget properties without having to delete and recreate the widget.

In this section, you will add a contextual toolbar that appears when the simple box widget is selected. This toolbar will contain a toggle button to mark the box as “secret,” which will blur its content to hide sensitive information.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--adding-an-attribute-to-the-schema">

#### Adding an attribute to the schema

First, you need to extend the simple box schema to support a new `secret` attribute. This attribute will be a boolean value that determines whether the box content should be blurred.

Update the schema definition in the `SimpleBoxEditing` plugin:

```
// simplebox/simpleboxediting.js

// Previously imported packages.
// ...

export default class SimpleBoxEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'insertSimpleBox', new InsertSimpleBoxCommand( this.editor ) );
    }

    _defineSchema() {
        const schema = this.editor.model.schema;

        schema.register( 'simpleBox', {
            inheritAllFrom: '$blockObject',

            // Added: Allow the 'secret' boolean attribute on simpleBox elements.
            allowAttributes: [ 'secret' ]
        } );

        // schema.register( 'simpleBoxTitle', {
        // 	...
        // } );
        //
        // schema.register( 'simpleBoxDescription', {
        // 	...
        // } );
        //
        // schema.addChildCheck( ( context, childDefinition ) => {
        // 	...
        // } );
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

The `allowAttributes` property tells the schema that the `simpleBox` element can have a `secret` attribute.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-a-command-2">

#### Creating a command

Now you need to create a command that will toggle the `secret` attribute. Create a new file `togglesimpleboxsecretcommand.js`:

```
// simplebox/togglesimpleboxsecretcommand.js

import { Command } from 'ckeditor5';

export default class ToggleSimpleBoxSecretCommand extends Command {
    refresh() {
        const editor = this.editor;
        const element = getClosestSelectedSimpleBoxElement( editor.model.document.selection );

        // Enable the command only when a simple box is selected.
        this.isEnabled = !!element;

        // Set the command value to the current state of the 'secret' attribute.
        this.value = !!( element && element.getAttribute( 'secret' ) );
    }

    execute( options = {} ) {
        const editor = this.editor;
        const model = editor.model;
        const simpleBox = getClosestSelectedSimpleBoxElement( model.document.selection );

        // Toggle the current state if no value is provided.
        const newValue = options.value === undefined ? !this.value : options.value;

        if ( simpleBox ) {
            model.change( writer => {
                if ( newValue ) {
                    // Set the 'secret' attribute to true when enabling.
                    writer.setAttribute( 'secret', true, simpleBox );
                } else {
                    // Remove the attribute entirely when disabling.
                    writer.removeAttribute( 'secret', simpleBox );
                }
            } );
        }
    }
}

function getClosestSelectedSimpleBoxElement( selection ) {
    const selectedElement = selection.getSelectedElement();

    // First, check if the selection is directly on a simple box.
    if ( !!selectedElement && selectedElement.is( 'element', 'simpleBox' ) ) {
        return selectedElement;
    } else {
        // Otherwise, find the closest simple box ancestor.
        return selection.getFirstPosition().findAncestor( 'simpleBox' );
    }
}

```

The command checks if the selection is inside a simple box and enables itself accordingly. The `value` property reflects the current state of the `secret` attribute (either `true` or `undefined`).

The `execute()` method accepts an optional `options` parameter with a `value` property. If no value is provided, the command automatically toggles the current state (hence its name, a “toggle” command). You can also explicitly pass a value if needed, but for most use cases, calling `editor.execute( 'toggleSimpleBoxSecret' )` without parameters is sufficient.

Register this command in the `SimpleBoxEditing` plugin:

```
// simplebox/simpleboxediting.js

import { Plugin, Widget, toWidget, toWidgetEditable } from 'ckeditor5';

import InsertSimpleBoxCommand from './insertsimpleboxcommand';
// Added: Import the new command.
import ToggleSimpleBoxSecretCommand from './togglesimpleboxsecretcommand';

export default class SimpleBoxEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'insertSimpleBox', new InsertSimpleBoxCommand( this.editor ) );

        // Added: Register the command to toggle the secret state.
        this.editor.commands.add( 'toggleSimpleBoxSecret', new ToggleSimpleBoxSecretCommand( this.editor ) );
    }


    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--updating-converters">

#### Updating converters

Next, you need to update the converters to handle the `secret` attribute. You need to convert it from the view to the model (upcast) and from the model to the view (downcast to both data and editing views).

Update the `_defineConverters()` method in the `SimpleBoxEditing` plugin:

```
// simplebox/simpleboxediting.js

// Previously imported packages.
// ...

export default class SimpleBoxEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'SimpleBoxEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'insertSimpleBox', new InsertSimpleBoxCommand( this.editor ) );
        this.editor.commands.add( 'toggleSimpleBoxSecret', new ToggleSimpleBoxSecretCommand( this.editor ) );
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {

        // <simpleBox> converters
        // (no changes)

        // Changed: Set custom property for widget detection.
        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'simpleBox',
            view: ( modelElement, { writer: viewWriter } ) => {
                const section = viewWriter.createContainerElement( 'section', { class: 'simple-box' } );

                // Set custom property to later check the view element.
                viewWriter.setCustomProperty( 'simpleBox', true, section );

                return toWidget( section, viewWriter, { label: 'simple box widget' } );
            }
        } );

        // Added: Handle the 'secret' attribute conversion between model and view.
        conversion.attributeToAttribute( {
            model: 'secret',
            view: {
                name: 'section',
                key: 'class',
                value: 'secret'
            }
        } );

        // <simpleBoxTitle> converters
        // (no changes)
        // ...

        // <simpleBoxDescription> converters
        // (no changes)
        // ...
    }
}

```

The element converters remain unchanged. The new part is the attribute conversion using the two-way [attributeToAttribute()](../../../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-attributeToAttribute) helper.

This single converter handles both directions: it maps the `secret` CSS class from the view to the `secret` model attribute (upcast). It also converts the model’s `secret` attribute back to a CSS class in both editing and data views (downcast).

Note that you also added a custom property to the widget in the editing downcast converter using [setCustomProperty()](../../../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-setCustomProperty). This custom property serves as a marker to identify simple box widgets in the view layer. Without this property, you would need to rely solely on CSS classes or element structure, which is less reliable.

You do not need to update the `createSimpleBox()` function because new simple boxes should not have the `secret` attribute by default (it will be `undefined`).

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-the-toolbar-button">

#### Creating the toolbar button

Now you can create a button that will toggle the `secret` attribute. You will use the [SwitchButtonView](../../../api/module%5Fui%5Fbutton%5Fswitchbuttonview-SwitchButtonView.html) class, which is a button with an on/off state.

Update the `SimpleBoxUI` plugin:

```
// simplebox/simpleboxui.js

// Added: Import SwitchButtonView for the toggle button.
import { ButtonView, SwitchButtonView, Plugin } from 'ckeditor5';

export default class SimpleBoxUI extends Plugin {
    init() {
        console.log( 'SimpleBoxUI#init() got called' );

        const editor = this.editor;
        const t = editor.t;

        editor.ui.componentFactory.add( 'simpleBox', locale => {
            // ... existing simpleBox button code ...
        } );

        // Added: Register the "secretSimpleBox" switch button for toggling the secret state.
        editor.ui.componentFactory.add( 'secretSimpleBox', locale => {
            const command = editor.commands.get( 'toggleSimpleBoxSecret' );
            const switchButton = new SwitchButtonView( locale );

            switchButton.set( {
                label: t( 'Secret box' ),
                withText: true
            } );

            // Bind the switch's state to the command's value and enabled state.
            switchButton.bind( 'isOn', 'isEnabled' ).to( command, 'value', 'isEnabled' );

        // Execute the command when the switch is toggled.
        // The command will automatically toggle based on its current state.
        this.listenTo( switchButton, 'execute', () => {
            editor.execute( 'toggleSimpleBoxSecret' );
        } );

            return switchButton;
        } );
    }
}

```

The switch button is bound to the `toggleSimpleBoxSecret` command. When clicked, it executes the command without any parameters, and the command automatically toggles its state based on its current `value`.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--registering-the-widget-toolbar">

#### Registering the widget toolbar

Now you need to create a plugin that will register the widget toolbar using the [WidgetToolbarRepository](../../../api/module%5Fwidget%5Fwidgettoolbarrepository-WidgetToolbarRepository.html) plugin. This plugin manages all widget toolbars in the editor and handles their positioning and visibility.

Create a new file `simpleboxtoolbar.js`:

```
// simplebox/simpleboxtoolbar.js

import { Plugin, WidgetToolbarRepository } from 'ckeditor5';

export default class SimpleBoxToolbar extends Plugin {
    static get requires() {
        return [ WidgetToolbarRepository ];
    }

    afterInit() {
        const editor = this.editor;
        const widgetToolbarRepository = editor.plugins.get( WidgetToolbarRepository );

        // Register a new toolbar for the simple box widget.
        widgetToolbarRepository.register( 'simpleBoxToolbar', {
            // Toolbar items come from the editor configuration.
            items: editor.config.get( 'simpleBox.toolbar' ),

            // Callback to determine which view element the toolbar should be attached to.
            getRelatedElement: getClosestSimpleBoxWidget
        } );
    }
}

function getClosestSimpleBoxWidget( selection ) {
    const selectionPosition = selection.getFirstPosition();

    if ( !selectionPosition ) {
        return null;
    }

    // Check if the selected element itself is a simple box widget.
    const viewElement = selection.getSelectedElement();

    if ( viewElement && isSimpleBoxWidget( viewElement ) ) {
        return viewElement;
    }

    // Otherwise, search up the view hierarchy for a simple box widget.
    let parent = selectionPosition.parent;

    while ( parent ) {
        if ( parent.is( 'element' ) && isSimpleBoxWidget( parent ) ) {
            return parent;
        }

        parent = parent.parent;
    }

    return null;
}

function isSimpleBoxWidget( viewElement ) {
    // Check if the element has our custom property and is a widget.
    return !!viewElement.getCustomProperty( 'simpleBox' ) && isWidget( viewElement );
}

```

The `SimpleBoxToolbar` plugin registers a widget toolbar in the `afterInit()` method. The toolbar configuration is read from the editor configuration under the `simpleBox.toolbar` property. The `getRelatedElement` function is a callback that returns the view element to which the toolbar should be attached. It searches for the closest simple box widget in the view hierarchy.

The helper function `isSimpleBoxWidget()` checks if a view element is a simple box widget by looking for the custom property you set earlier in the editing downcast converter.

Now register this plugin in the master `SimpleBox` plugin:

```
// simplebox/simplebox.js

import SimpleBoxEditing from './simpleboxediting';
import SimpleBoxUI from './simpleboxui';
// Added: Import the new toolbar plugin.
import SimpleBoxToolbar from './simpleboxtoolbar';
import { Plugin } from 'ckeditor5';

export default class SimpleBox extends Plugin {
    static get requires() {
        // Changed: Include the toolbar plugin in the requirements.
        return [ SimpleBoxEditing, SimpleBoxUI, SimpleBoxToolbar ];
    }
}

```

Finally, add the toolbar configuration to the editor setup in `main.js`:

```
// main.js

import SimpleBox from './simplebox/simplebox';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [
            Essentials, Paragraph, Heading, List, Bold, Italic,
            SimpleBox
        ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', 'simpleBox' ],
        // Added toolbar configuration.
        simpleBox: {
            toolbar: [ 'secretSimpleBox' ]
        }
    } );

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--styling-the-secret-state">

#### Styling the secret state

The last step is to add CSS styles that will blur the content of a secret simple box. Add these styles to your `index.html` file:

```
.simple-box.secret .simple-box-title,
.simple-box.secret .simple-box-description {
    filter: blur(4px);
    user-select: none;
    pointer-events: none;
}

.simple-box.secret::before {
    content: "Secret content";
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    background: rgba(0, 0, 0, 0.7);
    color: white;
    padding: 8px 16px;
    border-radius: 4px;
    font-size: 14px;
    z-index: 1;
}

```

These styles apply a blur effect to the title and description when the box is marked as secret. They also display a “Secret content” label on top of the blurred content.

Now, when you select a simple box widget, a contextual toolbar will appear with a “Secret box” toggle. Clicking it will blur the content of the box, making it unreadable. You can click it again to reveal the content.

This pattern of using [WidgetToolbarRepository](../../../api/module%5Fwidget%5Fwidgettoolbarrepository-WidgetToolbarRepository.html) is used throughout CKEditor 5 for features like images, tables, and other widgets. It provides a consistent way to add contextual controls to widgets without cluttering the main toolbar.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--demo">

### Demo

You can see the block widget implementation in action in the editor below. You can also check out the full [source code](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--final-solution) of this tutorial if you want to develop your own block widgets.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--final-solution">

### Final solution

If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/block-widget/final-project) available.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/block-widget/final-project final-project
cd final-project

npm install
npm run dev

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. **But do not install the dependencies.** Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Consequently, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html">source file: "ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html"</a>

## Implementing an inline widget

In this tutorial, you will learn how to implement an inline widget. You will build a “placeholder” feature that allows the users to insert predefined placeholders, like a date or a surname, into the document.

First, you will use widget utilities and conversion to define the behavior of this feature. Later on, you will use dropdown utilities to create a dropdown that will allow for inserting new placeholders. You will also learn how to use the editor configuration to define allowed placeholder names.

If you want to see the final product of this tutorial before you plunge in, check out the [demo](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--demo).

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--before-you-start">

### Before you start

This guide assumes that you are familiar with the widgets concept introduced in the [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html) tutorial, especially the [Let’s start](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--lets-start) and [Plugin structure](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--plugin-structure) sections. The tutorial will also reference various concepts from the [CKEditor 5 architecture](#ckeditor5/latest/framework/architecture/intro.html).

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--bootstrapping-the-project">

### Bootstrapping the project

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/inline-widget/starter-files inline-widget
cd inline-widget

npm install
npm run dev

```

This will create a new directory called `inline-widget` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

First, let’s define the `Placeholder` plugin. The project should have a structure shown below:

```
├── main.js
├── index.html
├── node_modules
├── package.json
├── placeholder
│   ├── placeholder.js
│   ├── placeholdercommand.js
│   ├── placeholderediting.js
│   ├── placeholderui.js
│   └── theme
│       └── placeholder.css
└─ ...

```

You can see that the placeholder feature has an established plugin structure: the master (glue) plugin (`placeholder/placeholder.js`), the “editing” (`placeholder/placeholderediting.js`) and the “UI” (`placeholder/placeholderui.js`) parts.

The master (glue) plugin:

```
// placeholder/placeholder.js

import { Plugin } from 'ckeditor5';

import PlaceholderEditing from './placeholderediting';
import PlaceholderUI from './placeholderui';

export default class Placeholder extends Plugin {
    static get requires() {
        return [ PlaceholderEditing, PlaceholderUI ];
    }
}

```

The UI part (empty for now):

```
// placeholder/placeholderui.js

import { Plugin } from 'ckeditor5';

export default class PlaceholderUI extends Plugin {
    init() {
        console.log( 'PlaceholderUI#init() got called' );
    }
}

```

And the editing part (empty for now):

```
// placeholder/placeholderediting.js

import { Plugin } from 'ckeditor5';

export default class PlaceholderEditing extends Plugin {
    init() {
        console.log( 'PlaceholderEditing#init() got called' );
    }
}

```

Finally, you need to load the `Placeholder` plugin in your `main.js` file:

```
// main.js

import Placeholder from './placeholder/placeholder';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Placeholder ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'undo', 'redo' ]
    } );

```

At this point, you can run the development server and see in the browser console that the plugins are being initialized.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--the-model-and-the-view-layers">

### The model and the view layers

The placeholder feature will be [defined](../../../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html) as an inline (text-like) element so it will be inserted into other editor blocks, like `<paragraph>`, that allow text. The placeholder will have a `name` attribute. This means that the model containing some text and a placeholder will look like this:

```
<paragraph>
    Hello <placeholder name="name"></placeholder>!
</paragraph>

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--defining-the-schema">

#### Defining the schema

The `<placeholder>` element should be treated as an object in `$text` so it must be defined with `inheritAllFrom: '$inlineObject'`. You will also need the `name` attribute.

You will also use this opportunity to import the theme file (`theme/placeholder.css`).

```
// placeholder/placeholderediting.js

import { Plugin } from 'ckeditor5';

import './theme/placeholder.css';                                              // ADDED

export default class PlaceholderEditing extends Plugin {
    init() {
        console.log( 'PlaceholderEditing#init() got called' );

        this._defineSchema();                                                  // ADDED
    }

    _defineSchema() {                                                          // ADDED
        const schema = this.editor.model.schema;

        schema.register( 'placeholder', {
            // Behaves like a self-contained inline object (e.g. an inline image)
            // allowed in places where $text is allowed (e.g. in paragraphs).
            // The inline widget can have the same attributes as text (for example linkHref, bold).
            inheritAllFrom: '$inlineObject',

            // The placeholder can have many types, like date, name, surname, etc:
            allowAttributes: [ 'name' ]
        } );
    }
}

```

The schema is defined so now you can define the model-view converters.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--defining-converters">

#### Defining converters

The HTML structure (data output) of the converter will be a `<span>` with the `placeholder` class. The text inside the `<span>` will be the placeholder’s name.

```
<span class="placeholder">{name}</span>

```

* [**Upcast conversion**](#ckeditor5/latest/framework/deep-dive/conversion/upcast.html). This view-to-model converter will look for `<span>`s with the `placeholder` class, read the `<span>`'s text and create model `<placeholder>` elements with the `name` attribute set accordingly.
* [**Downcast conversion**](#ckeditor5/latest/framework/deep-dive/conversion/downcast.html). The model-to-view conversion will be slightly different for “editing” and “data” pipelines as the “editing downcast” pipeline will use widget utilities to enable widget-specific behavior in the editing view. In both pipelines, the element will be rendered using the same structure.

```
import { Plugin, Widget, toWidget } from 'ckeditor5';

import './theme/placeholder.css';

export default class PlaceholderEditing extends Plugin {
    static get requires() {                                                    // ADDED
        return [ Widget ];
    }

    init() {
        console.log( 'PlaceholderEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();                                              // ADDED
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {                                                      // ADDED
        const conversion = this.editor.conversion;

        conversion.for( 'upcast' ).elementToElement( {
            view: {
                name: 'span',
                classes: [ 'placeholder' ]
            },
            model: ( viewElement, { writer: modelWriter } ) => {
                // Extract the "name" from "{name}".
                const name = viewElement.getChild( 0 ).data.slice( 1, -1 );

                return modelWriter.createElement( 'placeholder', { name } );
            }
        } );

        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'placeholder',
            view: ( modelItem, { writer: viewWriter } ) => {
                const widgetElement = createPlaceholderView( modelItem, viewWriter );

                // Enable widget handling on a placeholder element inside the editing view.
                return toWidget( widgetElement, viewWriter );
            }
        } );

        conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'placeholder',
            view: ( modelItem, { writer: viewWriter } ) => createPlaceholderView( modelItem, viewWriter )
        } );

        // Helper method for both downcast converters.
        function createPlaceholderView( modelItem, viewWriter ) {
            const name = modelItem.getAttribute( 'name' );

            const placeholderView = viewWriter.createContainerElement( 'span', {
                class: 'placeholder'
            } );

            // Insert the placeholder name (as a text).
            const innerText = viewWriter.createText( '{' + name + '}' );
            viewWriter.insert( viewWriter.createPositionAt( placeholderView, 0 ), innerText );

            return placeholderView;
        }
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--feature-styles">

#### Feature styles

The editing part imports the `./theme/placeholder.css` CSS file which describes how the placeholder is displayed in the editing view:

```
/* placeholder/theme/placeholder.css */

.placeholder {
    background: #ffff00;
    padding: 4px 2px;
    outline-offset: -2px;
    line-height: 1em;
    margin: 0 1px;
}

.placeholder::selection {
    display: none;
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--command">

#### Command

The [command](#ckeditor5/latest/framework/architecture/core-editor-architecture.html--commands) for the placeholder feature will insert a `<placeholder>` element (if allowed by the schema) at the selection. The command will accept the `options.value` parameter (other CKEditor 5 commands also use this pattern) to set the placeholder name.

```
// placeholder/placeholdercommand.js

import { Command } from 'ckeditor5';

export default class PlaceholderCommand extends Command {
    execute( { value } ) {
        const editor = this.editor;
        const selection = editor.model.document.selection;

        editor.model.change( writer => {
            // Create a <placeholder> element with the "name" attribute (and all the selection attributes)...
            const placeholder = writer.createElement( 'placeholder', {
                ...Object.fromEntries( selection.getAttributes() ),
                name: value
            } );

            // ... and insert it into the document. Put the selection on the inserted element.
            editor.model.insertObject( placeholder, null, null, { setSelection: 'on' } );
        } );
    }

    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;

        const isAllowed = model.schema.checkChild( selection.focus.parent, 'placeholder' );

        this.isEnabled = isAllowed;
    }
}

```

Import the created command and add it to the editor commands:

```
// placeholder/placeholderediting.js

import { Plugin, Widget, toWidget  } from 'ckeditor5';

import PlaceholderCommand from './placeholdercommand';                         // ADDED
import './theme/placeholder.css';

export default class PlaceholderEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'PlaceholderEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        // ADDED
        this.editor.commands.add( 'placeholder', new PlaceholderCommand( this.editor ) );
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--lets-see-it">

#### Let’s see it!

You should be able to execute the `placeholder` command to insert a new placeholder:

```
editor.execute( 'placeholder', { value: 'time' } );

```

This should result in:

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--fixing-position-mapping">

#### Fixing position mapping

If you play more with the widget (for example, try to select it by dragging the mouse from its right to the left edge), you will see the following error logged to the console:

```
Uncaught CKEditorError: model-nodelist-offset-out-of-bounds: Given offset cannot be found in the node list.

```

This error is thrown because there is a difference in text node mapping between the model and the view due to the different structures:

```
model:

foo<placeholder name="time"></placeholder>bar

view:

foo<span class="placeholder">{name}</span>bar

```

You could say that in the view there is “more” text than in the model. This means that some positions in the view cannot automatically map to positions in the model. Namely – those are positions inside the `<span>` element.

Fortunately, CKEditor 5 [allows customizing the mapping logic](../../../api/module%5Fengine%5Fconversion%5Fmapper-Mapper.html#event-viewToModelPosition). Also, since mapping to an empty model element is a pretty common scenario, there is a ready-to-use utility [viewToModelPositionOutsideModelElement()](../../../api/module%5Fwidget%5Futils.html#function-viewToModelPositionOutsideModelElement) that you can use here like that:

```
// placeholder/placeholderediting.js

import {
    Plugin,
    // MODIFIED
    Widget,
    toWidget,
    viewToModelPositionOutsideModelElement
} from 'ckeditor5';

import PlaceholderCommand from './placeholdercommand';
import './theme/placeholder.css';

export default class PlaceholderEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'PlaceholderEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'placeholder', new PlaceholderCommand( this.editor ) );

        // ADDED
        this.editor.editing.mapper.on(
            'viewToModelPosition',
            viewToModelPositionOutsideModelElement( this.editor.model, viewElement => viewElement.hasClass( 'placeholder' ) )
        );
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }
}

```

After adding the custom mapping, the mapping will work perfectly. Every position inside the view `<span>` element will be mapped to a position outside the `<placeholder>` in the model.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--creating-the-ui">

### Creating the UI

The UI part will provide a dropdown button from which the user can select a placeholder to insert into the editor.

CKEditor 5 Framework includes helpers to create different [dropdowns](#ckeditor5/latest/framework/architecture/ui-library.html--dropdowns) like toolbar or list dropdowns.

In this tutorial, you will create a dropdown with a list of available placeholders.

```
// placeholder/placeholderui.js

import {
    Plugin,
    UIModel,
    addListToDropdown,
    createDropdown,
    Collection
} from 'ckeditor5';

export default class PlaceholderUI extends Plugin {
    init() {
        const editor = this.editor;
        const t = editor.t;
        const placeholderNames = [ 'date', 'first name', 'surname' ];

        // The "placeholder" dropdown must be registered among the UI components of the editor
        // to be displayed in the toolbar.
        editor.ui.componentFactory.add( 'placeholder', locale => {
            const dropdownView = createDropdown( locale );

            // Populate the list in the dropdown with items.
            addListToDropdown( dropdownView, getDropdownItemsDefinitions( placeholderNames ) );

            dropdownView.buttonView.set( {
                // The t() function helps localize the editor. All strings enclosed in t() can be
                // translated and change when the language of the editor changes.
                label: t( 'Placeholder' ),
                tooltip: true,
                withText: true
            } );

            // Disable the placeholder button when the command is disabled.
            const command = editor.commands.get( 'placeholder' );
            dropdownView.bind( 'isEnabled' ).to( command );

            // Execute the command when the dropdown item is clicked (executed).
            this.listenTo( dropdownView, 'execute', evt => {
                editor.execute( 'placeholder', { value: evt.source.commandParam } );
                editor.editing.view.focus();
            } );

            return dropdownView;
        } );
    }
}

function getDropdownItemsDefinitions( placeholderNames ) {
    const itemDefinitions = new Collection();

    for ( const name of placeholderNames ) {
        const definition = {
            type: 'button',
            model: new UIModel( {
                commandParam: name,
                label: name,
                withText: true
            } )
        };

        // Add the item definition to the collection.
        itemDefinitions.add( definition );
    }

    return itemDefinitions;
}

```

Add the dropdown to the toolbar:

```
// main.js

import Placeholder from './placeholder/placeholder';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Placeholder ],

        // Insert the "placeholder" dropdown into the editor toolbar.
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'placeholder' ]
    } );

```

To make this plugin extensible, placeholder types will be read from the editor configuration.

The first step is to define the placeholder configuration in the editing plugin:

```
// Previously imported packages.
// ...

export default class PlaceholderEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        console.log( 'PlaceholderEditing#init() got called' );

        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'placeholder', new PlaceholderCommand( this.editor ) );

        this.editor.editing.mapper.on(
            'viewToModelPosition',
            viewToModelPositionOutsideModelElement( this.editor.model, viewElement => viewElement.hasClass( 'placeholder' ) )
        );

        this.editor.config.define( 'placeholderConfig', {                           // ADDED
            types: [ 'date', 'first name', 'surname' ]
        } );
    }

    _defineConverters() {
        // Previously defined converters.
        // ...
    }

    _defineSchema() {
        // Previously registered schema.
        // ...
    }
}

```

Now modify the UI plugin so it will read placeholder types from the configuration:

```
// placeholder/placeholderui.js

export default class PlaceholderUI extends Plugin {
    init() {
        const editor = this.editor;

        const placeholderNames = editor.config.get( 'placeholderConfig.types' );            // CHANGED

        editor.ui.componentFactory.add( 'placeholder', locale => {
            // Previously registered dropdown among UI components.
            // ...
        } );
    }
}

```

The plugin is now ready to accept the configuration. Check how this works by adding the `placeholderConfig` configuration in the editor’s `create()` method:

```
// Previously imported packages.
// ...

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
        plugins: [ Essentials, Paragraph, Heading, List, Bold, Italic, Widget, Placeholder ],
        toolbar: [ 'heading', 'bold', 'italic', 'numberedList', 'bulletedList', '|', 'placeholder' ],
        placeholderConfig: {
            types: [ 'date', 'color', 'first name', 'surname' ]                             // ADDED
        }
    } )
    // Promise handling.
    // ...

```

If you open the dropdown in the toolbar, you will see a new list of placeholders to insert.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--demo">

### Demo

You can see the placeholder widget implementation in action in the editor below. You can also check out the full [source code](#ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--final-solution) of this tutorial if you want to develop your own inline widgets.

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--final-solution">

### Final solution

If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/inline-widget/final-project) available.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/inline-widget/final-project final-project
cd final-project

npm install
npm run dev

```

<a id="ckeditor5/latest/framework/tutorials/widgets/implementing-an-inline-widget.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. **But do not install the dependencies.** Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Consequently, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html">source file: "ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html"</a>

## Using a React component in a block widget

In this tutorial, you will learn how to implement an editor plugin that uses the power of the [React](https://reactjs.org/) library inside the CKEditor 5 widget ecosystem. You will build a “Product preview” feature which renders an actual React component inside the editor to display some useful information about the product.

Later on, you will use the “Product preview” feature to build a simple React application that displays an editor next to the list of available products. The application will allow the user to insert the product into the editor content by clicking it on the list.

If you want to see the final product of this tutorial before you plunge in, check out the [demo](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--demo).

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--before-you-start">

### Before you start

There are a couple of things you should know before you start:

* Since you are here, you probably have at least some basic understanding of what React is and how it works. But what you might not know is that CKEditor 5 has an official [**rich text editor component for React**](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html) and it will be one of the key features used in this tutorial. Learning how to use it in your project is a good place to start.
* In this tutorial, you are going to implement a block editor widget and that itself could give you a headache. It is recommended to at least skim through the [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html) tutorial to get a grip on editor widgets, their API, and possible use cases.
* Various parts of the [CKEditor 5 architecture](#ckeditor5/latest/framework/architecture/intro.html) section will be referenced as you go. While reading them is not necessary to finish this tutorial, it is recommended to read those guides at some point to get a better understanding of the mechanisms used in this tutorial.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--lets-start">

### Let’s start

The easiest way to get started is to grab the starter project using the commands below.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/react-widget/starter-files react-widget
cd react-widget

npm install
npm run dev

```

This will create a new directory called `react-widget` with the necessary files. The `npm install` command will install all the dependencies, and `npm run dev` will start the development server.

The editor with some basic plugins is created in the `main.js` file.

Open the URL displayed in your terminal. If everything goes well, you should see a “Hello world” application in your web browser, which might not be much, but it is a good start:

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--application-structure">

### Application structure

Nothing warms the heart of a developer like a good “Hello world!” But you probably agree that what you created is not the most useful application and it is time to change that. In the next sections, you will create some React components and CKEditor 5 classes to bring some real logic to the application.

To keep some order in the project, you will put [CKEditor classes](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--ckeditor-classes) in the `/ckeditor` directory and [React components](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--react-components) in the `/react` directory. [Images](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--styles-and-assets) will land in the `/public` directory. By the time you are finished with this tutorial, the structure of the project should look as follows:

```
├── public
│    ├── fields.jpg
│    ├── malta.jpg
│    ├── tajmahal.jpg
│    └── umbrellas.jpg
├── src
│    ├── ckeditor
│    │   ├── insertproductpreviewcommand.js
│    │   └── productpreviewediting.js
│    ├── react
│    │   ├── productlist.jsx
│    │   └── productpreview.jsx
│    ├── app.jsx
│    ├── main.jsx
│    └── styles.css
├── index.html
├── package.json
└── node_modules

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--ckeditor-classes">

### CKEditor classes

Create the CKEditor–side logic that supports product preview widgets in the editor content:

* The [ProductPreviewEditing](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--editing-plugin) plugin will extend the editor data layers to support the new kind of content.
* The [InsertProductPreviewCommand](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--command) provides an easy way for the “outside world” to insert product previews into the editor content.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--editing-plugin">

#### Editing plugin

The `ProductPreviewEditing` plugin defines the `productPreview` element in the editor [model](#ckeditor5/latest/framework/architecture/editing-engine.html--model) and specifies the way it is converted to the editing and data [views](#ckeditor5/latest/framework/architecture/editing-engine.html--view).

* In the **data view**, the `productPreview` is represented as an empty `<section class="product" data-id="..."></section>` element with a `data-id` attribute associating it with a particular product. A semantic representation of the product saved in the database can be then consumed in the frontend by retrieving a fresh preview using the `data-id`. Since it does not carry any formatting or styling, the data representation will never get outdated, even if the layout or styles of the application change in the future.
* In the **editing view**, on the other hand, the product preview is a [block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html), which acts as a self–contained piece of content the user can insert, copy, and paste as a whole but they cannot change its internal structure. Inside the widget, there is a [UIElement](../../../api/module%5Fengine%5Fview%5Fuielement-ViewUIElement.html) with a `.product__react-wrapper` class that hosts a React `<ProductPreview>` component. Each time the model element is upcasted, the rendering function specified in the [editor configuration](#ckeditor5/latest/getting-started/setup/configuration.html) (`editor.config.products.productRenderer`) mounts a React component inside the `UIElement`.

The differences in data representations of the product preview are summarized in the following table:

| Data structure            | Representation                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Model                     | <productPreview id="..." />                                                                                                                            |
| Editing view              | <section class="product" data-id="...">     <div class="product\_\_react-wrapper">         <ProductPreview /> // React component     </div> </section> |
| Data view (editor output) | <section class="product" data-id="..."></section>                                                                                                      |

Here is the full source code of the `ProductPreviewEditing` editor plugin:

```
// ckeditor/productpreviewediting.js

import { Plugin, Widget, toWidget } from 'ckeditor5';

import InsertProductPreviewCommand from './insertproductpreviewcommand';

export default class ProductPreviewEditing extends Plugin {
    static get requires() {
        return [ Widget ];
    }

    init() {
        this._defineSchema();
        this._defineConverters();

        this.editor.commands.add( 'insertProduct', new InsertProductPreviewCommand( this.editor ) );
    }

    _defineSchema() {
        const schema = this.editor.model.schema;

        schema.register( 'productPreview', {
            // Behaves like a self-contained object (e.g. an image).
            isObject: true,

            // Allow in places where other blocks are allowed (e.g. directly in the root).
            allowWhere: '$block',

            // Each product preview has an ID. A unique ID tells the application which
            // product it represents and makes it possible to render it inside a widget.
            allowAttributes: [ 'id' ]
        } );
    }

    _defineConverters() {
        const editor = this.editor;
        const conversion = editor.conversion;
        const renderProduct = editor.config.get( 'products' ).productRenderer;

        // <productPreview> converters ((data) view → model)
        conversion.for( 'upcast' ).elementToElement( {
            view: {
                name: 'section',
                classes: 'product'
            },
            model: ( viewElement, { writer: modelWriter } ) => {
                // Read the "data-id" attribute from the view and set it as the "id" in the model.
                return modelWriter.createElement( 'productPreview', {
                    id: parseInt( viewElement.getAttribute( 'data-id' ) )
                } );
            }
        } );

        // <productPreview> converters (model → data view)
        conversion.for( 'dataDowncast' ).elementToElement( {
            model: 'productPreview',
            view: ( modelElement, { writer: viewWriter } ) => {
                // In the data view, the model <productPreview> corresponds to:
                //
                // <section class="product" data-id="..."></section>
                return viewWriter.createEmptyElement( 'section', {
                    class: 'product',
                    'data-id': modelElement.getAttribute( 'id' )
                } );
            }
        } );

        // <productPreview> converters (model → editing view)
        conversion.for( 'editingDowncast' ).elementToElement( {
            model: 'productPreview',
            view: ( modelElement, { writer: viewWriter } ) => {
                // In the editing view, the model <productPreview> corresponds to:
                //
                // <section class="product" data-id="...">
                //     <div class="product__react-wrapper">
                //         <ProductPreview /> (React component)
                //     </div>
                // </section>
                const id = modelElement.getAttribute( 'id' );

                // The outermost <section class="product" data-id="..."></section> element.
                const section = viewWriter.createContainerElement( 'section', {
                    class: 'product',
                    'data-id': id
                } );

                // The inner <div class="product__react-wrapper"></div> element.
                // This element will host a React <ProductPreview /> component.
                const reactWrapper = viewWriter.createRawElement( 'div', {
                    class: 'product__react-wrapper'
                }, function( domElement ) {
                    // This the place where React renders the actual product preview hosted
                    // by a UIElement in the view. You are using a function (renderer) passed as
                    // editor.config.products#productRenderer.
                    renderProduct( id, domElement );
                } );

                viewWriter.insert( viewWriter.createPositionAt( section, 0 ), reactWrapper );

                return toWidget( section, viewWriter, { label: 'product preview widget' } );
            }
        } );
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--command">

#### Command

The `InsertProductPreviewCommand` inserts the `productPreview` element into the model at the current selection position. It is executed by the `<ProductPreview>` React component in the application sidebar to insert a widget into the editor content.

Learn more about widget commands in the [Implementing a block widget](#ckeditor5/latest/framework/tutorials/widgets/implementing-a-block-widget.html--creating-a-command) guide. You can see this command in action in the section about the [main application component](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--main-application-component).

```
// ckeditor/insertproductpreviewcommand.js

import { Command } from 'ckeditor5';

export default class InsertProductPreviewCommand extends Command {
    execute( id ) {
        this.editor.model.change( writer => {
            // Insert <productPreview id="...">*</productPreview> at the current selection position
            // in a way which will result in creating a valid model structure.
            this.editor.model.insertContent( writer.createElement( 'productPreview', { id } ) );
        } );
    }

    refresh() {
        const model = this.editor.model;
        const selection = model.document.selection;
        const allowedIn = model.schema.findAllowedParent( selection.getFirstPosition(), 'productPreview' );

        this.isEnabled = allowedIn !== null;
    }
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--react-components">

### React components

It is time to define the React side of the application that renders the actual layout:

* The [<ProductList>](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--product-list) component displays a bunch of `<ProductPreview>` children and allows the user to click them to insert them into the editor.
* The [<ProductPreview>](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--product-preview) component represents a single product with its name, price tag and a background image.
* The [<App>](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--main-application-component) component glues all the things together.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--product-list">

#### Product list

The `<ProductList>` React component renders instances of `<ProductPreview>`. When clicked, the preview executes a callback passed in [“props”](https://reactjs.org/docs/components-and-props.html) that inserts its own copy into the editor content by executing the ['insertProduct'](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--command) editor command. The list is displayed in the sidebar of the [application](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--main-application-component).

```
// react/productlist.js

import ProductPreview from './productpreview';

export default function ProductList( props ) {
    return (
        <div className='app__product-list'>
            <h3>Products</h3>
            <ul>
                {props.products.map( ( product ) => {
                    return (
                        <li key={ product.id }>
                            <ProductPreview
                                id={ product.id }
                                onClick={ props.onClick }
                                { ...product }
                            />
                        </li>
                    );
                })}
            </ul>
            <p><b>Tip</b>: Clicking the product will add it to the editor.</p>
        </div>
    );
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--product-preview">

#### Product preview

The actual preview of the product, with its name, price and an image. Instances of the `<ProductPreview>` component populate both the [<ProductList>](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--product-list) and the [editor widgets](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--editing-plugin) in the content.

Clicking a preview in the sidebar executes the ['insertProduct'](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--command) editor command and inserts the same preview into the editor content.

```
// react/productpreview.js

export default function ProductPreview( props ) {
    return (
        <div
            className='product-preview'
            style={ {
                '--product-image': `url(${ props.image })`
            } }
        >
            <button
                className='product-preview__add'
                onClick={ () => props.onClick( props.id ) }
                title='Add to the offer'
            >
                <span>+</span>
            </button>
            <span className='product-preview__name'>{ props.name }</span>
            <span className='product-preview__price'>from { props.price }</span>
        </div>
    );
}

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--main-application-component">

#### Main application component

At the moment, you have CKEditor classes that bring the product preview into the content, a list of products, and a product component ready. It is time to glue things together in the `App` component.

You are going to extend the [main application file](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--lets-start) skeleton that you created earlier in this tutorial so it renders the [official <CKEditor> React component](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html) on the left side, and the list of available products on the right.

Have a look at the full source code of the `App` function:

```
// app.jsx

// Imports necessary to run a React application.
import { useState } from 'react';
import { createRoot } from 'react-dom/client';
// The official <CKEditor> component for React.
import { CKEditor } from '@ckeditor/ckeditor5-react';
// The base editor class and features required to run the editor.
import {
    ClassicEditor,
    Bold,
    Italic,
    Underline,
    Essentials,
    Heading,
    Link,
    Paragraph,
    Table,
    TableToolbar
} from 'ckeditor5';
// The official CKEditor 5 instance inspector. It helps understand the editor view and model.
import CKEditorInspector from '@ckeditor/ckeditor5-inspector';
// CKEditor plugin implementing a product widget to be used in the editor content.
import ProductPreviewEditing from './ckeditor/productpreviewediting';
// React components to render the list of products and the product preview.
import ProductList from './react/productlist';
import ProductPreview from './react/productpreview';

import 'ckeditor5/ckeditor5.css';
import './styles.css';

// The React application function component. It renders the editor and the product list.
export default function App( props ) {
    // A place to store the reference to the editor instance created by the <CKEditor> component.
    // The editor instance is created asynchronously and is only available when the editor is ready.
    const [ editorRef, setEditorRef ] = useState( null );
    // The initial editor data. It is bound to the editor instance and will change as
    // the user types and modifies the content of the editor.
    const [ editorData, setEditorData ] = useState( `<h2>Check our last minute deals!</h2>

    <p>Aenean erat conubia pretium libero habitant turpis vivamus dignissim molestie, phasellus libero! Curae; consequat cubilia mattis. Litora non iaculis tincidunt.</p>
    <section class="product" data-id="2">&nbsp;</section>
    <p>Mollis gravida parturient ad maecenas euismod consectetur lacus rutrum urna eget ligula. Nisi imperdiet scelerisque natoque scelerisque cubilia nulla gravida. Eleifend malesuada pharetra est commodo venenatis aenean habitasse curae; fusce elit.</p>
    <section class="product" data-id="1">&nbsp;</section>

    <h3>Other deals</h3>
    <p>Ultricies dapibus placerat orci natoque fames commodo facilisi sollicitudin. Sed hendrerit mi dis non lacinia ipsum. Luctus fames scelerisque auctor pellentesque mi nunc mattis, amet sapien.</p>

    <figure class="table">
        <table>
            <thead>
                <tr>
                    <th>Our deal</th>
                    <th>Why this one?</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>
                        <section class="product" data-id="3">&nbsp;</section>
                    </td>
                    <td>Nascetur, nullam hac nibh curabitur elementum. Est ridiculus turpis adipiscing erat maecenas habitant montes. Curabitur mauris ut luctus semper. Neque orci auctor luctus accumsan quam cursus purus condimentum dis?</td>
                </tr>
                <tr>
                    <td>
                        <section class="product" data-id="4">&nbsp;</section>
                    </td>
                    <td>Elementum condimentum convallis porttitor cubilia consectetur cum. In pretium neque accumsan pharetra. Magna in quisque dignissim praesent facilisi diam. Ad habitant ultricies at faucibus. Ultricies auctor sodales massa nisi eget sem porta?</td>
                </tr>
            </tbody>
        </table>
    </figure>` );

    return (
        // The application renders two columns:
        // * in the left one, the <CKEditor> and the textarea displaying live
        //   editor data are rendered.
        // * in the right column, a <ProductList> is rendered with available <ProductPreviews>
        //   to choose from.
        <div ref={ setEditorRef } className='app'>
            { editorRef && <>
                <div className='app__offer-editor' key='offer-editor'>
                    <CKEditor
                        editor={ ClassicEditor }
                        // The configuration of the <CKEditor> instance.
                        config={ {
                            licenseKey: 'GPL', // Or '<YOUR_LICENSE_KEY>'.
                            plugins: [
                                // A set of editor features to be enabled and made available to the user.
                                Essentials, Heading, Bold, Italic, Underline,
                                Link, Paragraph, Table, TableToolbar,
                                // Your custom plugin implementing the widget is loaded here.
                                ProductPreviewEditing
                            ],
                            toolbar: [
                                'heading',
                                '|',
                                'bold', 'italic', 'underline',
                                '|',
                                'link', 'insertTable',
                                '|',
                                'undo', 'redo'
                            ],
                            table: {
                                contentToolbar: [
                                    'tableColumn',
                                    'tableRow',
                                    'mergeTableCells'
                                ]
                            },
                            // The configuration of the Products plugin. It specifies a function that will allow
                            // the editor to render a React <ProductPreview> component inside a product widget.
                            products: {
                                productRenderer: ( id, domElement ) => {
                                    const product = props.products.find( product => product.id === id );
                                    const root = createRoot( domElement );

                                    root.render(
                                        <ProductPreview id={ id } { ...product } />
                                    );
                                }
                            }
                        } }
                        data={ editorData }
                        onReady={ ( editor ) => {
                            // A function executed when the editor has been initialized and is ready.
                            // It synchronizes the initial data state and saves the reference to the editor instance.
                            setEditorRef( editor );
                            // CKEditor&nbsp;5 inspector allows you to take a peek into the editor's model and view
                            // data layers. Use it to debug the application and learn more about the editor.
                            CKEditorInspector.attach( editor );
                        } }
                        onChange={ ( evt, editor ) => {
                            // A function executed when the user types or modifies the editor content.
                            // It updates the state of the application.
                            setEditorData( editor.getData() );
                        } }
                    />
                </div>
                <ProductList
                    key='product-list'
                    products={ props.products }
                    onClick={ ( id  ) => {
                        editorRef.execute( 'insertProduct', id );
                        editorRef.editing.view.focus();
                    } }
                />
            </> }
        </div>
    )
}

```

The JavaScript code is ready, but to run the application you need to specify a couple of product definitions. Do that when mounting the `<App>` component:

```
// main.jsx

import ReactDOM from 'react-dom/client';
import App from './app';

// Render the <App> in the <div class="root"></div> element found in the DOM.
ReactDOM.createRoot( document.getElementById( 'root' ) ).render(
    <App
        // Feeding the application with predefined products.
        // In a real-life application, this sort of data would be loaded
        // from a database. To keep this tutorial simple, a few
        // hard–coded product definitions will be used.
        products={ [
            {
                id: 1,
                name: 'Colors of summer in Poland',
                price: '$1500',
                image: 'fields.jpg'
            },
            {
                id: 2,
                name: 'Mediterranean sun on Malta',
                price: '$1899',
                image: 'malta.jpg'
            },
            {
                id: 3,
                name: 'Tastes of Asia',
                price: '$2599',
                image: 'umbrellas.jpg'
            },
            {
                id: 4,
                name: 'Exotic India',
                price: '$2200',
                image: 'tajmahal.jpg'
            }
        ] }
    />
)

```

Each product comes with its own image (like `malta.jpg`), which should be stored in the `public/` directory to load correctly with the CSS `background-image`. Learn more about styles in the [next section](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--styles-and-assets).

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--styles-and-assets">

### Styles and assets

The application needs some styling to look good. You are going to put them in the `src/styles.css` file imported in your `app.jsx` file:

```
/* src/styles.css */

/* --- General application styles --------------------------------------------------- */

.app {
    display: flex;
    flex-direction: row;
    justify-content: center;
    font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
    margin: 0 auto;
}

.app h2 {
    font-size: 1.3em;
}

.app textarea {
    width: 100%;
    height: 150px;
    font-family: 'Courier New', Courier, monospace;
    box-sizing: border-box;
    font-size: 14px;
}

/* --- Product offer editor styles ----------------------------------------------------- */

.app .app__offer-editor {
    flex: 1 1 auto;
    max-width: 800px;
}

/* --- Generic product preview styles --------------------------------------------------- */

.app .product-preview {
    background-repeat: no-repeat;
    background-position: center;
    background-image: var(--product-image);
    background-size: cover;
    height: 150px;
    position: relative;
    overflow: hidden;
    box-shadow: 1px 1px 3px hsla(0, 0%, 0%, .3);
    min-width: 160px;
}

.app .product-preview .product-preview__name {
    padding: 10px;
    background: hsl(0, 0%, 100%);
    font-weight: bold;
    position: absolute;
    bottom: 0;
    left: 0;
    right: 0;
}

.app .product-preview .product-preview__price {
    position: absolute;
    top: 0;
    right: 0;
    display: block;
    background: hsl(346, 100%, 56%);
    padding: 6px 10px;
    min-width: 50px;
    text-align: center;
    color: hsl(0, 0%, 100%);
    text-transform: uppercase;
    font-size: .8em;
}

.app .product-preview .product-preview__add {
    display: none;
}

/* --- Product list styles --------------------------------------------------- */

.app .app__product-list {
    margin-left: 20px;
    padding: 20px;
    min-width: 400px;
    border-left: 1px solid hsl(0, 0%, 87%);
}

.app .app__product-list h2 {
    margin-top: 10px;
}

.app .app__product-list ul {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-gap: 10px;
    margin-top: 10px;
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.app .app__product-list .product-preview {
    opacity: .7;
}

.app .app__product-list .product-preview:hover {
    opacity: 1;
}

.app .app__product-list .product-preview:hover .product-preview__add {
    display: block;
}

.app .app__product-list .product-preview .product-preview__add {
    display: none;
    position: absolute;
    width: 40px;
    height: 40px;
    top: 45%;
    left: 50%;

    border: 0;
    padding: 0;
    cursor: pointer;
    font-weight: bold;
    text-align: center;
    border-radius: 100px;
    background: hsl(0, 0%, 100%);
    transform: translate(-50%, -50%);
    box-shadow: 2px 2px 2px hsla(0, 0%, 0%, .3);
}

.app .app__product-list .product-preview .product-preview__add span {
    font-size: 25px;
    vertical-align: middle;
    color: hsl(0, 0%, 24%);
    line-height: 40px;
    display: inline-block;
}

.app .app__product-list .product-preview .product-preview__name {
    font-size: 10px;
}

.app .app__product-list .product-preview .product-preview__price {
    font-size: 10px;
}

/* --- In-editor product widget styles --------------------------------------------------- */

.app .ck-content .product {
    margin: 1em;
    animation: slideUp 0.3s ease;
}

@keyframes slideUp {
    0% {
        opacity: 0;
        transform: translateY(1em);
    }
    100% {
        opacity: 1;
        transform: translateY(0);
    }
}

```

The product preview (`.product-preview` class) uses `background-image: var(--product-image)` to set its background. It means that all images must be stored in the `public/` directory to load properly.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--demo">

### Demo

You can see the entire application working below. Click the products in the sidebar to add them to the editor. You can also check out the [full source code](#ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--final-solution) of this tutorial if you want to extend it further or use it as base for your application.

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--final-solution">

### Final solution

If you got lost at any point in the tutorial or want to go straight to the solution, there is a repository with the [final project](https://github.com/ckeditor/ckeditor5-tutorials-examples/tree/main/react-widget/final-project) available.

```
npx -y degit ckeditor/ckeditor5-tutorials-examples/react-widget/final-project final-project
cd final-project

npm install
npm run dev

```

<a id="ckeditor5/latest/framework/tutorials/widgets/using-react-in-a-widget.html--adapt-this-tutorial-to-cdn">

### Adapt this tutorial to CDN

If you want to use the editor from CDN, you can adapt this tutorial by following these steps.

First, clone the repository the same way as before. But do not install the dependencies. Instead, open the `index.html` file and add the following tags:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 Framework – tutorial CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello world!</p>
        </div>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script type="module" src="/main.js"></script>
    </body>
</html>

```

The CSS file contains the editor and content styles. Consequently, you do not need to import styles into your JavaScript file.

```
// Before:
import 'ckeditor5/ckeditor5.css';

// After:
// No need to import the styles.

```

The script tag loads the editor from the CDN. It exposes the global variable `CKEDITOR`. You can use it in your project to access the editor class and plugins. That is why you must change the import statements to destructuring in the JavaScript files:

```
// Before:
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';

// After:
const { ClassicEditor, Essentials, Bold, Italic, Paragraph } = CKEDITOR;

```

After following these steps and running the `npm run dev` command, you should be able to open the editor in the browser.

<a id="ckeditor5/latest/getting-started/index.html">source file: "ckeditor5/latest/getting-started/index.html"</a>

## Getting started with CKEditor 5

CKEditor 5 is a flexible editing framework that provides every type of WYSIWYG editing solution imaginable. From editors similar to Google Docs and Medium to Notion, Slack, or Twitter-like applications, all is possible within a single editing framework. It is a modern JavaScript rich-text editor with MVC architecture, custom data model, and virtual DOM, written from scratch in TypeScript with excellent support for modern bundlers. Find out the most convenient way to start using it!

<a id="ckeditor5/latest/getting-started/index.html--are-you-new-to-ckeditor-5">

### Are you new to CKEditor 5?

If your dive into using our WYSIWYG editor is only starting, find out how to kick off this adventure easily. You have a few methods to choose from:

* [Using CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/) for the smoothest setup with live preview and multiple integration options.
* [Using npm](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-ckeditor-5-using-npm), where you use a JavaScript package and build the editor with a bundler.
* [Using CDN](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-ckeditor-5-from-cdn), where you use our cloud-distributed CDN in a no-build setup.
* [Using a ZIP file](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-ckeditor-5-from-a-zip-file), where you download the ready-to-run files and copy them to your project.
* Choosing one of the [pre-made integrations with popular frameworks](#ckeditor5/latest/getting-started/index.html--ckeditor-5-framework-integrations).

<a id="ckeditor5/latest/getting-started/index.html--ckeditor-5-framework-integrations">

### CKEditor 5 framework integrations

Do you want to use a framework? Native integrations with the most popular libraries will save you time and effort. There are several official integrations so far:

* Integrate CKEditor 5 with **Angular** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/angular.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/angular.html).
* Integrate CKEditor 5 with **React** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).
* Integrate CKEditor 5 with **Next.js** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/next-js.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/next-js.html).
* Integrate CKEditor 5 with **Nuxt** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/nuxt.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html).
* Integrate CKEditor 5 with **Vue.js 3.x** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html).
* Integrate CKEditor 5 with **Vue.js 2.x** using [npm](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html).
* Integrate CKEditor 5 with **Salesforce** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/salesforce.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html).
* Integrate CKEditor 5 with **Svelte** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/svelte.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/svelte.html).
* Integrate CKEditor 5 with **Spring-boot** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/spring-boot.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html).
* Integrate CKEditor 5 with **jQuery** using [CDN](#ckeditor5/latest/getting-started/installation/cloud/jquery.html) or [npm](#ckeditor5/latest/getting-started/installation/self-hosted/jquery.html).
* Integrate CKEditor 5 with [**Sharepoint SPFx**](#ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html).
* Integrate CKEditor 5 with [**Drupal**](#ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html).
* Integrate CKEditor 5 with [**CSS frameworks**](#ckeditor5/latest/getting-started/installation/css.html).

<a id="ckeditor5/latest/getting-started/index.html--support-for-other-frameworks">

#### Support for other frameworks

CKEditor 5 is a native JavaScript rich-text editing component written in TypeScript. As such, it is framework-agnostic and **can be integrated with any JavaScript framework and application**. It does not require any uncommon techniques or technologies to be used. Therefore, unless the framework you use has atypical limitations, CKEditor 5 is compatible with it.

CKEditor 5 is also compatible with popular CSS frameworks such as Bootstrap or Foundation. Such integrations, however, often require additional changes and adjustments that we have gathered [in this guide](#ckeditor5/latest/getting-started/installation/css.html).

We plan to provide more integrations with time. We would like to [hear your ideas](https://github.com/ckeditor/ckeditor5/issues/1002) about what we should work on next.

<a id="ckeditor5/latest/getting-started/index.html--migrating-from-ckeditor-4">

### Migrating from CKEditor 4?

If you are familiar with our previous, discontinued product and would like to switch, check the **[Migration section](#ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html)**. You will find a useful upgrade guide there to help you switch with the least effort.

<a id="ckeditor5/latest/getting-started/index.html--configuring-ckeditor-5">

### Configuring CKEditor 5

Once you install your copy of CKEditor 5, take some time to [configure it](#ckeditor5/latest/getting-started/setup/configuration.html) before first use. Set up data-saving methods, editor toolbars, and UI.

You may also take the [step-by-step tutorial](#ckeditor5/latest/framework/tutorials/crash-course/editor.html) that will guide you through the installation and configuration of the editor.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html">source file: "ckeditor5/latest/getting-started/installation/cloud/angular.html"</a>

## Integrating CKEditor 5 with Angular from CDN

Angular is a TypeScript-based, open-source, single-page web application framework. The CKEditor 5 component for Angular supports integrating different editor types.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--quick-start">

### Quick start

This guide assumes you already have an Angular project. To create such a project, you can use Angular CLI. Refer to the [Angular documentation](https://angular.io/cli) to learn more.

First, install the [CKEditor 5 WYSIWYG editor component for Angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular):

```
npm install @ckeditor/ckeditor5-angular

```

Angular is a TypeScript-first environment, so you may need to import TypeScript types for CKEditor. Depending on the plugins and features you use, you may also need to install the required open-source and premium packages:

```
npm install --save-dev ckeditor5 # Open-source plugin types.
npm install --save-dev ckeditor5-premium-features # Premium features plugin types.

```

In the below example, the `loadCKEditorCloud` helper is used to load the editor code and plugins from CDN. To use CKEditor 5 with CDN, you need to import the function and call it inside the `ngOnInit` lifecycle hook with the `version` provided in the configuration. To use premium plugins, set the `premium` property to `true` and provide your license key in the configuration. For more information about the `loadCKEditorCloud` helper, see the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide.

```
// app.component.ts

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { CKEditorModule, loadCKEditorCloud, CKEditorCloudResult } from '@ckeditor/ckeditor5-angular';
import type { ClassicEditor, EditorConfig } from 'https://cdn.ckeditor.com/typings/ckeditor5.d.ts';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    imports: [ CommonModule, CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    public Editor: typeof ClassicEditor | null = null;

    public config: EditorConfig | null = null;

    public ngOnInit(): void {
        loadCKEditorCloud( {
            version: '48.0.0',
            premium: true
        } ).then( this._setupEditor.bind( this ) );
    }

    private _setupEditor ( cloud: CKEditorCloudResult<{ version: '48.0.0', premium: true }> ) {
        const {
            ClassicEditor,
            Essentials,
            Paragraph,
            Bold,
            Italic
        } = cloud.CKEditor;

        const { FormatPainter } = cloud.CKEditorPremiumFeatures;

        this.Editor = ClassicEditor;
        this.config = {
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
        };
    }
}

```

In the example above, the `EditorConfig` type is imported from the `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` package, while the editor itself loads from the CDN. Note that `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` is not an actual URL to the CKEditor 5 typings file but a synthetic TypeScript module providing type definitions for the editor. The `ckeditor5` or `ckeditor5-premium-features` packages supply the actual types, which depend on the `@ckeditor/ckeditor5-angular` package.

Finally, use the `<ckeditor>` tag in the template to run the rich text editor. The usage is the same regardless of the plugin configuration.

```
<!-- app.component.html -->

<ckeditor
    *ngIf="( Editor && config )"
    data="<p>Hello, world!</p>"
    [editor]="Editor"
    [config]="config"
>
</ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--supported-input-properties">

### Supported `@Input` properties

The following `@Input` properties are supported by the CKEditor 5 rich text editor component for Angular:

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--editor-required">

#### `editor` (required)

The [Editor](#ckeditor5/latest/getting-started/setup/editor-lifecycle.html) which provides the static [create()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) method to create an instance of the editor:

```
<ckeditor [editor]="Editor"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--config">

#### `config`

The [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor:

```
<ckeditor [config]="{ toolbar: [ 'heading', '|', 'bold', 'italic' ] }"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--data">

#### `data`

The initial data of the editor. It can be a static value:

```
<ckeditor data="<p>Hello, world!</p>"></ckeditor>

```

or a shared parent component’s property

```
@Component( {
    // ...
} )
export class MyComponent {
    public editorData;

    private _setupEditor( cloud ) {
        this.editorData = '<p>Hello, world!</p>';
    }
    // ...
}

```

```
<ckeditor [data]="editorData"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--tagname">

#### `tagName`

The tag name of the HTML element on which the rich text editor will be created.

The default tag is `<div>`.

```
<ckeditor tagName="textarea"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--disabled">

#### `disabled`

Controls the editor’s [read–only](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) state:

```
@Component( {
    // ...
} )
export class MyComponent {
    public isDisabled;
    // ...
    private _setupEditor( cloud ) {
        this.isDisabled = false;
    }
    toggleDisabled() {
        this.isDisabled = !this.isDisabled;
    }
}

```

```
<ckeditor [disabled]="isDisabled"></ckeditor>

<button (click)="toggleDisabled()">
    {{ isDisabled ? 'Enable editor' : 'Disable editor' }}
</button>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--watchdog">

#### `watchdog`

An instance of the [ContextWatchdog](../../../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html) class that is responsible for providing the same context to multiple editor instances and restarting the whole structure in case of crashes.

```
import { loadCKEditorCloud } from '@ckeditor/ckeditor5-angular';

@Component( {
    // ...
} )
export class MyComponent {
    public editor;
    public watchdog: any;
    public ready;

    ngOnInit() {
        loadCKEditorCloud( {
            version: '48.0.0',
        } ).then( this._setupEditor.bind( this ) );
    }

    private _setupEditor( cloud ) {
        const {
            ClassicEditor,
            ContextWatchdog,
            Context
        } = cloud.CKEditor;

        const contextConfig = {
            // Your context configuration.
        };

        this.Editor = ClassicEditor;
        this.ready = false;

        this.watchdog = new ContextWatchdog( Context );

        this.watchdog.create( contextConfig )
            .then( () => {
                this.ready = true;
            } );
    }
}

```

```
<div *ngIf="ready">
    <ckeditor [watchdog]="watchdog"></ckeditor>
    <ckeditor [watchdog]="watchdog"></ckeditor>
    <ckeditor [watchdog]="watchdog"></ckeditor>
</div>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--editorwatchdogconfig">

#### `editorWatchdogConfig`

If the `watchdog` property is not used, [EditorWatchdog](../../../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html) will be used by default. `editorWatchdogConfig` property allows for passing a [config](../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) to that watchdog.

```
@Component( {
    // ...
} )
export class MyComponent {
    public myWatchdogConfig;

    private _setupEditor( cloud ) {
        this.myWatchdogConfig = {
            crashNumberLimit: 5,
            // ...
        };
    }
    // ...
}

```

```
<ckeditor [editorWatchdogConfig]="myWatchdogConfig"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--disabletwowaydatabinding">

#### `disableTwoWayDataBinding`

Allows disabling the two-way data binding mechanism. The default value is `false`.

The reason for the introduction of this option is performance issues in large documents. By default, while using the `ngModel` directive, whenever the editor’s data is changed, the component must synchronize the data between the editor instance and the connected property. This results in calling the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) function, which causes a massive slowdown while typing in large documents.

This option allows the integrator to disable the default behavior and only call the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method on demand, which prevents the slowdowns. You can read more in the [relevant issue](https://github.com/ckeditor/ckeditor5-angular/issues/141).

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--supported-output-properties">

### Supported `@Output` properties

The following `@Output` properties are supported by the CKEditor 5 rich text editor component for Angular:

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--ready">

#### `ready`

Fired when the editor is ready. It corresponds with the [editor#ready](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) event.  
It is fired with the editor instance.

Note that this method might be called multiple times. Apart from initialization, it is also called whenever the editor is restarted after a crash. Do not keep the reference to the editor instance internally, because it will change in case of a restart. Instead, you should use the `watchdog.editor` property.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--change">

#### `change`

Fired when the content of the editor has changed. It corresponds with the [editor.model.document#change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.  
It is fired with an object containing the editor and the CKEditor 5 `change:data` event object.

```
<ckeditor [editor]="Editor" (change)="onChange($event)"></ckeditor>

```

```
import { ClassicEditor } from 'ckeditor5';
import { ChangeEvent } from '@ckeditor/ckeditor5-angular/ckeditor.component';

@Component( {
    // ...
} )
export class MyComponent {
    public Editor;

    private _setupEditor( cloud ) {
        const {
            ClassicEditor
        } = cloud.CKEditor;

        this.Editor = ClassicEditor;
    }

    public onChange( { editor }: ChangeEvent ) {
        const data = editor.getData();

        console.log( data );
    }
    // ...
}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--blur">

#### `blur`

Fired when the editing view of the editor is blurred. It corresponds with the [editor.editing.view.document#blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.  
It is fired with an object containing the editor and the CKEditor 5 `blur` event data.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--focus">

#### `focus`

Fired when the editing view of the editor is focused. It corresponds with the [editor.editing.view.document#focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.  
It is fired with an object containing the editor and the CKEditor 5 `focus` event data.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--error">

#### `error`

Fired when the editor crashes. Once the editor has crashed, the internal watchdog mechanism restarts the editor and fires the [ready](#ckeditor5/latest/getting-started/installation/cloud/angular.html--ready) event.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--integration-with-ngmodel">

### Integration with `ngModel`

The component implements the [ControlValueAccessor](https://angular.io/api/forms/ControlValueAccessor) interface and works with the `ngModel`. Here is how to use it:

Create some model in your component to share with the editor:

```
@Component( {
    // ...
} )
export class MyComponent {
    public model;

    private _setupEditor( cloud ) {
        this.model = {
            editorData: '<p>Hello, world!</p>'
        };
    }
    // ...
}

```

Use the model in the template to enable a two–way data binding:

```
<ckeditor [(ngModel)]="model.editorData" [editor]="Editor"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--styling">

#### Styling

The CKEditor 5 rich text editor component for Angular can be styled using the component style sheet or using a global style sheet. See how to set the CKEditor 5 component’s height using these two approaches.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--setting-the-height-via-the-component-style-sheet">

#### Setting the height via the component style sheet

First, create a (S)CSS file in the parent component’s directory and style the given editor’s part preceded by the `:host` and `::ng-deep` pseudo selectors:

```
/* src/app/app.component.css */

:host ::ng-deep .ck-editor__editable_inline {
    min-height: 500px;
}

```

Then, in the parent component, add the relative path to the above style sheet:

```
/* src/app/app.component.ts */

@Component( {
    // ...
    styleUrls: [ './app.component.css' ]
} )

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--setting-the-height-via-a-global-style-sheet">

##### Setting the height via a global style sheet

To style the component using a global style sheet, first, create it:

```
/* src/styles.css */

.ck-editor__editable_inline {
    min-height: 500px;
}

```

Then, add it to the `angular.json` configuration file:

```
"architect": {
    "build": {
        "options": {
            "styles": [
                { "input": "src/styles.css" }
            ]
        }
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--setting-the-placeholder">

##### Setting the placeholder

To display [the placeholder](#ckeditor5/latest/features/editor-placeholder.html) in the main editable element, set the `root.placeholder` field in the CKEditor 5 rich text editor component configuration:

```
@Component( {
    // ...
} )
export class MyComponent {
    public config;

    private _setupEditor( cloud ) {
        // ...
        this.config = {
            root: {
                placeholder: 'Type the content here!'
            }
        }
    }

}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--accessing-the-editor-instance">

#### Accessing the editor instance

The CKEditor 5 rich text editor component provides all the functionality needed for most use cases. When access to the full CKEditor 5 API is needed, you can get the editor instance with an additional step.

To do this, create a template reference variable `#editor` pointing to the `<ckeditor>` component:

```
<ckeditor #editor [editor]="Editor"></ckeditor>

```

Then get the `<ckeditor>` component using a property decorated by `@ViewChild( 'editor' )` and access the editor instance when needed:

```
@Component()
export class MyComponent {
    @ViewChild( 'editor' ) editorComponent: CKEditorComponent;

    public getEditor() {
        // Warning: This may return "undefined" if the editor is hidden behind the `*ngIf` directive or
        // if the editor is not fully initialised yet.
        return this.editorComponent.editorInstance;
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--using-the-document-editor-type">

#### Using the Document editor type

If you want to use the [document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html), you need to [add the toolbar to the DOM manually](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create):

```
// app.component.ts

import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { CKEditorCloudResult, CKEditorModule, loadCKEditorCloud } from '@ckeditor/ckeditor5-angular';
import { DecoupledEditor, EditorConfig } from 'https://cdn.ckeditor.com/typings/ckeditor5.d.ts';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: [ './app.component.css' ],
    imports: [ CommonModule, CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';

    public Editor: typeof DecoupledEditor | null = null;

    public config: EditorConfig | null = null;

    public ngOnInit(): void {
        loadCKEditorCloud( {
            version: '48.0.0'
        } ).then( this._setupEditor.bind( this ) );
    }

    private _setupEditor( cloud: CKEditorCloudResult<{ version: '48.0.0'}>) {
        const {
            DecoupledEditor,
            Essentials,
            Paragraph,
            Bold,
            Italic
        } = cloud.CKEditor;

        this.Editor = DecoupledEditor;
        this.config = {
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Paragraph, Bold, Italic ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
        };
    }

    public onReady( editor: DecoupledEditor ) {
        const element = editor.ui.getEditableElement()!;
        const parent = element.parentElement!;

        parent.insertBefore(
            editor.ui.view.toolbar.element!,
            element
        );
    }
}

```

And then, link the method in the template:

```
<!-- app.component.html -->

<ckeditor
  *ngIf="(Editor && config)"
  data="<p>Hello, world!</p>"
  [editor]="Editor"
  [config]="config"
  (ready)="onReady($event)"
>
</ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a few **ready-to-use integrations** featuring collaborative editing in Angular applications:

* [CKEditor 5 with real-time collaboration features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-angular)
* [CKEditor 5 with real-time collaboration and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-revision-history-for-angular)
* [CKEditor 5 with the revision history feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/revision-history-for-angular)
* [CKEditor 5 with the track changes feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/track-changes-for-angular)

It is not mandatory to build applications on top of the above samples; however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official Angular component. To translate the editor, pass the languages you need into the `translations` array inside the configuration of the `loadCKEditorCloud` function.

```
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { CKEditorModule, loadCKEditorCloud, CKEditorCloudResult } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor, EditorConfig } from 'https://cdn.ckeditor.com/typings/ckeditor5.d.ts';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    imports: [ CommonModule, CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    public Editor: typeof ClassicEditor | null = null;

    public config: EditorConfig | null = null;

    public ngOnInit(): void {
        loadCKEditorCloud( {
            version: '48.0.0',
            translations: [ 'es' ]
        } ).then( this._setupEditor.bind( this ) );
    }

    private _setupEditor ( cloud: CKEditorCloudResult<{ version: '48.0.0'}> ) {
        const {
            ClassicEditor,
            Paragraph,
            Essentials,
            Bold,
            Italic
        } = cloud.CKEditor;

        this.Editor = ClassicEditor;
        this.config = {
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
        };
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--supported-angular-versions">

### Supported Angular versions

Because of the breaking changes in the Angular library output format, the `@ckeditor/ckeditor5-angular` package is released in the following versions to support various Angular ecosystems:

| CKEditor 5 Angular component version | Angular version | Details                                                                                                                                                                                                      |
| ------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Actively supported versions          |                 |                                                                                                                                                                                                              |
| ^11                                  | 19+             | Requires CKEditor 5 in version [47](https://github.com/ckeditor/ckeditor5/releases/tag/v47.0.0) or higher.                                                                                                   |
| Past releases (no longer maintained) |                 |                                                                                                                                                                                                              |
| ^10                                  | 16+             | Requires CKEditor 5 in version [46](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.0) or higher.                                                                                                   |
| ^9                                   | 16+             | Migration to TypeScript 5\. Declaration files are not backward compatible. Requires CKEditor 5 in version [43](https://github.com/ckeditor/ckeditor5/releases/tag/v43.0.0) or higher.                        |
| ^8                                   | 13+             | Requires CKEditor 5 in version [42](https://github.com/ckeditor/ckeditor5/releases/tag/v42.0.0) or higher.                                                                                                   |
| ^7                                   | 13+             | Changes in peer dependencies ([issue](https://github.com/ckeditor/ckeditor5-angular/issues/376)). Requires CKEditor 5 in version [37](https://github.com/ckeditor/ckeditor5/releases/tag/v37.0.0) or higher. |
| ^6                                   | 13+             | Requires CKEditor 5 in version [37](https://github.com/ckeditor/ckeditor5/releases/tag/v37.0.0) or higher.                                                                                                   |
| ^5                                   | 13+             | Requires Angular in version 13+ or higher.                                                                                                                                                                   |
| ^4                                   | 9.1+            | Requires CKEditor 5 in version [34](https://github.com/ckeditor/ckeditor5/releases/tag/v34.0.0) or higher.                                                                                                   |
| ^3                                   | 9.1+            | Requires Node.js in version 14 or higher.                                                                                                                                                                    |
| ^2                                   | 9.1+            | Migration to TypeScript 4\. Declaration files are not backward compatible.                                                                                                                                   |
| ^1                                   | 5.x - 8.x       | Angular versions no longer maintained.                                                                                                                                                                       |

All available Angular versions are [listed on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular), where they can be pulled from.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of the CKEditor 5 rich text editor component for Angular is available on GitHub at <https://github.com/ckeditor/ckeditor5-angular>.

<a id="ckeditor5/latest/getting-started/installation/cloud/angular.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/dotnet.html">source file: "ckeditor5/latest/getting-started/installation/cloud/dotnet.html"</a>

## Integrating CKEditor 5 with .NET from CDN

As a pure JavaScript/TypeScript library, the CKEditor 5 HTML editor will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 in a non-JS framework of your choice, for example, Microsoft’s [.NET](https://dotnet.microsoft.com/).

<a id="ckeditor5/latest/getting-started/installation/cloud/dotnet.html--setting-up-the-project">

### Setting up the project

For the purpose of this guide, we will use a basic ASP.NET Core project created with `dotnet new webapp`. You can refer to the [ASP.NET Core documentation](https://learn.microsoft.com/en-us/aspnet/core/getting-started/?view=aspnetcore-7.0) to learn how to set up a project in the framework.

<a id="ckeditor5/latest/getting-started/installation/cloud/dotnet.html--using-from-cdn">

### Using from CDN

The folder structure of the created project should resemble the one below:

```
├── bin
├── obj
├── Pages
│   ├── Index.cshtml
│   └── ...
├── Properties
├── wwwroot
│   ├── css
│   ├── js
│   ├── lib
│   └── favicon.ico
├── appsettings.Development.json
├── appsettings.json
└── ...

```

First, modify the `Index.cshtml` file in the `Pages` directory to include the CKEditor 5 scripts and styles. All necessary scripts and links are in the HTML snippet below. You can copy and paste them into your template. Open-source and premium features are in separate files, so there are different tags for both types of plugins. Add tags for premium features only if you use them.

```
@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div class="text-center">
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
    .main-container {
        width: 795px;
        margin-left: auto;
        margin-right: auto;
    }
    </style>

    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>
</div>

```

Both attached earlier scripts expose global variables named `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES`. You can use them to access the editor class and plugins. In our example, we use object destructuring (JavaScript feature) to access the editor class from the open-source global variable with a basic set of plugins. You can access premium plugins from the other variable the same way. Then, we pass the whole configuration to the `create()` method. Be aware that you need a proper [license key](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) to use premium features.

```
const {
    ClassicEditor,
    Essentials,
    Bold,
    Italic,
    Font,
    Paragraph
} = CKEDITOR;
const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
            'formatPainter'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Now, we need to put our script in the previous template. We put it under the `<div>` element, so the editor can attach to it. Your final template should look like this:

```
@page
@model IndexModel
@{
    ViewData["Title"] = "Home page";
}

<div class="text-center">
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
    .main-container {
        width: 795px;
        margin-left: auto;
        margin-right: auto;
    }
    </style>

    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>

    <script>
        const {
            ClassicEditor,
            Essentials,
            Bold,
            Italic,
            Font,
            Paragraph
        } = CKEDITOR;
        const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

        ClassicEditor
            .create( {
                attachTo: document.querySelector( '#editor' ),
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                toolbar: [
                    'undo', 'redo', '|', 'bold', 'italic', '|',
                    'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                    'formatPainter'
                ]
            } )
            .then( /* ... */ )
            .catch( /* ... */ );
    </script>
</div>

```

Finally, in the root directory of your .NET project, run `dotnet watch run` to see the app in action.

<a id="ckeditor5/latest/getting-started/installation/cloud/dotnet.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html">source file: "ckeditor5/latest/getting-started/installation/cloud/electron.html"</a>

## Integrating CKEditor 5 with Electron from CDN

[Electron](https://www.electronjs.org/) is an open-source framework that allows developers to create cross-platform desktop applications using web technologies such as HTML, CSS, and JavaScript. It combines the Node.js runtime and the Chromium rendering engine, enabling a single codebase to be used for cross-platform apps that work on Windows, macOS, and Linux.

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--quick-start">

### Quick start

This guide will show you how to integrate CKEditor 5 with an Electron application using the CDN. If you are new to Electron, check out their [official tutorial](https://www.electronjs.org/docs/latest/tutorial/tutorial-prerequisites).

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--setting-up-an-electron-project">

#### Setting up an Electron project

The quickest way to set up an Electron project is to use Electron Forge’s `create-electron-app` command. [Follow the Getting Started guide](https://www.electronforge.io/) to create the application.

When executing `npx create-electron-app@latest my-app` in the terminal, you will be prompted to choose a bundler and a language. For the sake of this tutorial, we have chosen to use Vite and vanilla JavaScript.

When the setup is finished, you should be able to go to the app’s directory and run it by executing:

```
cd my-app
npm start

```

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--integrating-ckeditor-5-with-electron-using-cdn">

### Integrating CKEditor 5 with Electron using CDN

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--project-structure">

#### Project structure

After following all the steps described so far, your app’s structure should resemble this one:

```
├── forge.config.js
├── index.html
├── node_modules/
├── package-lock.json
├── package.json
├── src/
│   ├── index.css
│   ├── main.js
│   ├── preload.js
│   └── renderer.js
├── vite.main.config.mjs
├── vite.preload.config.mjs
└── vite.renderer.config.mjs

```

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--implementing-the-editor">

#### Implementing the editor

Inside the `src/` folder, create a new file `editor.js` with the following content:

```
const {
    ClassicEditor,
    Essentials,
    Bold,
    Italic,
    Font,
    Paragraph
} = CKEDITOR;

const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
            'formatPainter'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This code imports all the necessary CKEditor 5 plugins and initializes the editor instance with the provided configuration.

Now modify the `index.html` file so it looks like this:

```
<!doctype html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Hello World!</title>

    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    </head>
    <body>
        <h1>Hello Electron and CKEditor 5!</h1>
        <p>Welcome to your Electron application. Below you should see a working instance of CKEditor 5:</p>

        <div id="editor"></div>

        <script src="./src/editor.js"></script>

        <script type="module" src="/src/renderer.js"></script>
    </body>
</html>

```

Here we adjusted the structure to include the `<div>` placeholder for the editor instance. We have also added CDN links to the editor’s styles, source files, and finally the `editor.js` file, which is responsible for tying everything together and initializing the editor.

You can now execute `npm start` to run the Electron app. It should automatically open a window with an editor instance ready to be used:

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--obtaining-a-premium-features-license-key">

### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/cloud/electron.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html">source file: "ckeditor5/latest/getting-started/installation/cloud/jquery.html"</a>

## Integrating CKEditor 5 with jQuery from CDN

This guide will walk you through the process of integrating CKEditor 5 with jQuery using the CDN approach. jQuery is a fast, small, and feature-rich JavaScript library that simplifies HTML document traversal and manipulation, event handling, and animation. By combining it with CKEditor 5, you can leverage jQuery’s powerful DOM manipulation capabilities while enjoying the rich editing experience that CKEditor 5 provides.

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html--setting-up-a-jquery-page">

### Setting up a jQuery page

To begin integrating CKEditor 5 with jQuery, you first need to create an HTML page that includes jQuery from the CDN. Start by creating a basic HTML structure and include jQuery using a CDN link. The jQuery library should be loaded before any custom scripts that depend on it. This ensures that it is available when your custom code executes. Once it is loaded, you can start using its methods and selectors in your JavaScript code.

Here is a complete HTML page setup with jQuery integrated from CDN:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor&nbsp;5 with jQuery Integration</title>

    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
</head>
<body>
    <div id="editor">
        <p>Hello from CKEditor&nbsp;5 with jQuery!</p>
    </div>

    <script>
        $( document ).ready( () => {
            // jQuery code will go here
            console.log( 'jQuery is loaded and ready!' );
        } );
    </script>
</body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html--installing-ckeditor-5-from-cdn">

### Installing CKEditor 5 from CDN

After setting up your jQuery page, the next step is to integrate CKEditor 5 from CDN. You need to include both the CSS style sheets and JavaScript files for CKEditor 5\. The CSS files contain all the necessary styles for the editor’s user interface and content display. The JavaScript files contain the editor engine and all the plugins you want to use.

First, add the CKEditor 5 style sheet to ensure proper styling of the editor interface. The style sheet should be included in the head section of your HTML document. Then, include the CKEditor 5 JavaScript file that contains the editor engine and core functionality. This script should be loaded after jQuery but before your custom initialization code.

Here are the required CDN links for CKEditor 5:

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

```

Now, modify your existing jQuery integration to include CKEditor 5 initialization. You can use jQuery’s document ready function to ensure the DOM is fully loaded before initializing the editor. The CKEditor 5 initialization code should be placed within the jQuery ready function to ensure proper timing and availability of all required resources.

Here is the complete integration code combining jQuery and CKEditor 5:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor&nbsp;5 with jQuery Integration</title>

    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
</head>
<body>
    <div id="editor">
        <p>Hello from CKEditor&nbsp;5 with jQuery!</p>
    </div>

    <script>
        $( document ).ready( () => {
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;

            ClassicEditor
                .create( {
                    attachTo: $( '#editor' )[ 0 ],
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ]
                } )
                .then( editor => {
                    // Editor initialized successfully.
                    console.log( 'CKEditor&nbsp;5 initialized with jQuery!' );
                } )
                .catch( error => {
                    console.error( 'Error initializing CKEditor&nbsp;5:', error );
                } );
        } );
    </script>
</body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html--installing-ckeditor-5-premium-features-from-cdn">

### Installing CKEditor 5 Premium Features from CDN

To extend your CKEditor 5 and jQuery integration with premium features, you need to include additional resources from the CKEditor 5 Premium Features CDN. Just like with the non-premium features, you need to include both CSS and JavaScript files for the premium features.

Start by adding the premium features style sheet to your HTML head section. This style sheet should be loaded after the main CKEditor 5 style sheet to ensure proper cascading and override of styles when necessary. The premium features style sheet contains all the additional styles needed for premium UI components and features.

Here is the premium features style sheet link:

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

```

Next, include the premium features JavaScript file. This script should be loaded after the main CKEditor 5 script but before your custom initialization code. The premium features script provides access to premium plugins and functionality that you can then use in your editor configuration.

Here is the premium features script tag:

```
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>

```

Update your jQuery integration code to include premium features. You can import premium plugins from the `CKEDITOR_PREMIUM_FEATURES` object and add them to your editor configuration. For example, you can add the Format Painter feature which allows users to copy formatting from one text selection and apply it to another.

Here is the complete integration with premium features:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor&nbsp;5 with jQuery and Premium Features</title>

    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
</head>
<body>
    <div id="editor">
        <p>Hello from CKEditor&nbsp;5 with jQuery and Premium Features!</p>
    </div>

    <script>
        $( document ).ready( () => {
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;
            const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor
                .create( {
                    attachTo: $( '#editor' )[ 0 ],
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                        'formatPainter'
                    ]
                } )
                .then( editor => {
                    // Editor initialized successfully with premium features.
                    console.log( 'CKEditor&nbsp;5 with premium features initialized using jQuery!' );
                } )
                .catch( error => {
                    console.error( 'Error initializing CKEditor&nbsp;5 with premium features:', error );
                } );
        } );
    </script>
</body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html--obtaining-a-premium-features-license-key">

#### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/cloud/jquery.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/laravel.html">source file: "ckeditor5/latest/getting-started/installation/cloud/laravel.html"</a>

## Integrating CKEditor 5 with Laravel from CDN

As a pure JavaScript/TypeScript library, the CKEditor 5 HTML editor will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 in a non-JS framework of your choice, for example, the PHP-based [Laravel](https://laravel.com/).

<a id="ckeditor5/latest/getting-started/installation/cloud/laravel.html--setting-up-the-project">

### Setting up the project

This guide assume you have a Laravel project. You can create a basic Laravel project using [Composer](https://getcomposer.org/). Refer to the [Laravel documentation](https://laravel.com/docs/10.x/installation) to learn how to set up a project in the framework.

<a id="ckeditor5/latest/getting-started/installation/cloud/laravel.html--using-from-cdn">

### Using from CDN

The folder structure of the created project should resemble the one below:

```
├── app
├── bootstrap
├── config
├── database
├── public
│   ├── .htaccess
│   ├── favicon.ico
│   ├── index.php
│   └── robots.txt
├── resources
│   ├── views
|      ├── welcome.blade.php
|      └── ...
├── routes
└── ...

```

First, modify the `welcome.blade.php` file in the `resources/views` directory to include the CKEditor 5 scripts and styles. All necessary scripts and links are in the HTML snippet below. You can copy and paste them into your template. Open-source and premium features are in separate files, so there are different tags for both types of plugins. Add tags for premium features only if you use them.

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 - Quick start CDN</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
    .main-container {
        width: 795px;
        margin-left: auto;
        margin-right: auto;
    }
    </style>
</head>
<body>
    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>
</body>
</html>

```

Both previously attached scripts expose global variables named `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES`. You can use them to access the editor class and plugins. In our example, we use object destructuring (JavaScript feature) to access the editor class from the open-source global variable with a basic set of plugins. You can access premium plugins from the other variable the same way. Then, we pass the whole configuration to the `create()` method. Be aware that you need a proper [license key](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) to use premium features.

```
<script>
    const {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Font,
        Paragraph
    } = CKEDITOR;
    const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

Now, we need to put our script in the previous template. We need to put the script under the `<div>` element, so the editor can attach to it. Your final template should look like this:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 - Quick start CDN</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/43.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
        .main-container {
            width: 795px;
            margin-left: auto;
            margin-right: auto;
        }
    </style>
</head>
<body>
    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>
    <script>
        const {
            ClassicEditor,
            Essentials,
            Bold,
            Italic,
            Font,
            Paragraph
        } = CKEDITOR;
        const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

        ClassicEditor
            .create( {
                attachTo: document.querySelector( '#editor' ),
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                toolbar: [
                    'undo', 'redo', '|', 'bold', 'italic', '|',
                    'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                    'formatPainter'
                ]
            } )
            .then( /* ... */ )
            .catch( /* ... */ );
    </script>
</body>
</html>

```

Finally, in the root directory of your Laravel project, run `php artisan serve` to see the editor in action.

<a id="ckeditor5/latest/getting-started/installation/cloud/laravel.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/next-js.html">source file: "ckeditor5/latest/getting-started/installation/cloud/next-js.html"</a>

## Integrating CKEditor 5 with Next.js from CDN

[Next.js](https://nextjs.org/) is a React meta-framework that helps create full-stack web applications. It offers different rendering strategies like server-side rendering (SSR), client-side rendering (CSR), or static site generation (SSG). Additionally, it provides file-based routing, automatic code splitting, and other handy features out of the box.

Next.js 13 introduced a new App Router as an alternative to the previous Pages Router. App Router supports server components and is more server-centric than Pages Router, which is client-side oriented.

CKEditor 5 does not support server-side rendering, but you can integrate it with the Next.js framework. In this guide, you will add the editor to a Next.js project using both routing paradigms. For this purpose, you will need [Next.js CLI](https://nextjs.org/docs/app/api-reference/create-next-app), and the official [CKEditor 5 React component](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).

<a id="ckeditor5/latest/getting-started/installation/cloud/next-js.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Next project. To create such a project, you can use CLI like `create-next-app`. Refer to the [Next.js documentation](https://nextjs.org/docs/app/api-reference/create-next-app) to learn more.

<a id="ckeditor5/latest/getting-started/installation/cloud/next-js.html--using-from-cdn">

### Using from CDN

Next.js is based on React, so we need to install the [CKEditor 5 WYSIWYG editor component for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react):

```
npm install @ckeditor/ckeditor5-react

```

You will use the installed dependency in a React component. Create a new component in the components directory, for example, `components/custom-editor.js`. Inside the component file, import all necessary dependencies. Then, create a functional component that returns the CKEditor 5 React component. The example below shows how to use the component with both open-source and premium plugins.

The App Router, by default, uses server components. It means you need to mark a component as client-side explicitly. You can achieve that by using the `'use client'` directive at the top of the file, above your imports. You do not need the directive if you use the Pages Router.

In the below example, the `useCKEditorCloud` hook is used to load the editor code and plugins from CDN. To use premium plugins, set the `premium` property to `true` and provide your license key in the configuration. For more information about the `useCKEditorCloud` helper, see the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide.

```
// components/custom-editor.js
'use client' // Required only in App Router.

import React from 'react';
import { CKEditor, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

const CustomEditor = () => {
    const cloud = useCKEditorCloud( {
        version: '48.0.0',
        premium: true
    } );

    if ( cloud.status === 'error' ) {
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const {
        ClassicEditor,
        Essentials,
        Paragraph,
        Bold,
        Italic
    } = cloud.CKEditor;

    const { FormatPainter } = cloud.CKEditorPremiumFeatures;

    return (
        <CKEditor
            editor={ ClassicEditor }
            data={ '<p>Hello world!</p>' }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
            } }
        />
    );
};

export default CustomEditor;

```

The `CustomEditor` component is ready to be used inside a page. The page’s directory will differ depending on the selected routing strategy.

The CKEditor 5 HTML editor is a client-side text editor and relies on the browser APIs, so you need to disable server-side rendering for our custom component. You can lazily load the component using the `dynamic()` function built into Next.js.

Prepare a wrapper for the `CustomEditor` component to load it on the client side.

```
// components/client-side-custom-editor.js
'use client' // Required only in App Router.

import dynamic from 'next/dynamic';

const ClientSideCustomEditor = dynamic( () => import( '@/components/custom-editor' ), { ssr: false } );

export default ClientSideCustomEditor;

```

And then use it in your application.

```
// app/page.js (App Router)
// pages/index.js (Pages Router)

import ClientSideCustomEditor from '@/components/client-side-custom-editor';

function Home() {
  return (
    <ClientSideCustomEditor />
  );
}

export default Home;

```

You can run your project now. If you chose `create-next-app`, type `npm run dev` to see your application in the browser.

Also, pay attention to the import path – this guide uses the [default import alias](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases) (@). If you did not configure it, change the path

In the example above, we only used basic features of the `<CKEditor>` component. To learn more about additional features and configuration options, refer to the [React integration guide](#ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html).

<a id="ckeditor5/latest/getting-started/installation/cloud/next-js.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/nuxt.html">source file: "ckeditor5/latest/getting-started/installation/cloud/nuxt.html"</a>

## Integrating CKEditor 5 with Nuxt from CDN

[Nuxt](https://nuxt.com/) is a Vue.js meta-framework for creating full-stack web applications. It offers everything you would expect from a modern framework, including various rendering modes, file-based routing, automatic code splitting, a large ecosystem of plugins and hosting integrations, and more.

The CKEditor 5 HTML editor does not support server-side rendering, but you can integrate it with the Nuxt framework. In this guide, you will add the editor to a Nuxt project. For this purpose, you will need a [Nuxt project](https://nuxt.com/docs/getting-started/installation) and the official [CKEditor 5 Vue component](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html).

<a id="ckeditor5/latest/getting-started/installation/cloud/nuxt.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Nuxt project. To create such a project, follow the [Nuxt installation guide](https://nuxt.com/docs/getting-started/installation).

<a id="ckeditor5/latest/getting-started/installation/cloud/nuxt.html--using-from-cdn">

### Using from CDN

Nuxt is based on Vue.js, so install the [CKEditor 5 WYSIWYG editor component for Vue.js](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue), too:

```
npm install @ckeditor/ckeditor5-vue

```

You will use the installed dependencies in a Vue.js component. Create a new component in the `components` directory, for example, `components/Editor.vue`. It will use the `<ckeditor>` component to run the editor. The following example shows a single file component with open-source and premium CKEditor 5 plugins.

```
<template>
    <ckeditor
        v-if="editor"
        v-model="data"
        :editor="editor"
        :config="config"
    />
</template>

<script setup>
import { ref, computed } from 'vue';
import { Ckeditor, useCKEditorCloud } from '@ckeditor/ckeditor5-vue';

const cloud = useCKEditorCloud( {
    version: '48.0.0',
    premium: true
} );

const data = ref( '<p>Hello world!</p>' );

const editor = computed( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    return cloud.data.value.CKEditor.ClassicEditor;
} );

const config = computed( () => {
        if ( !cloud.data.value ) {
        return null;
    }

    const { Essentials, Paragraph, Bold, Italic } = cloud.data.value.CKEditor;
    const { FormatPainter } = cloud.data.value.CKEditorPremiumFeatures;

    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    };
} );
</script>

```

In the above example, the `useCKEditorCloud` hook loads the editor code and plugins from CDN. To use premium plugins, set the `premium` property to `true` and provide your license key in the configuration. For more information about the `useCKEditorCloud` helper, see the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide.

Now, you can import and use the `Editor.vue` component anywhere in your application.

```
<template>
    <ClientOnly>
        <Editor />
    </ClientOnly>
</template>

```

Notice that the `<Editor>` component is wrapped in a `<ClientOnly>` component. It is required because CKEditor 5 does not support server-side rendering. The `<ClientOnly>` component ensures that the editor is rendered only on the client side.

You can run your project now using the `npm run dev` command to see your application in the browser.

In the example above, we only used basic features of the `<ckeditor>` component. To learn more about additional features and configuration options, refer to the [Vue.js integration guide](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html).

<a id="ckeditor5/latest/getting-started/installation/cloud/nuxt.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html">source file: "ckeditor5/latest/getting-started/installation/cloud/quick-start.html"</a>

## Installing Vanilla JS CKEditor 5 from CDN

CKEditor 5 is a powerful, rich text editor you can embed in your web application. This guide will show you the fastest way to start using it.

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-ckeditor-5-from-cdn">

### Installing CKEditor 5 from CDN

CDN is an alternative method of running CKEditor 5\. You can start using it in just a few steps and with a few tags.

Start by attaching a link to style sheets. They contain all styles for the editor’s UI and content. You can also include your styles if you like. Refer to the [content styles](#ckeditor5/latest/getting-started/setup/css.html--styling-the-published-content) guide for more information.

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

```

Then, you need to attach the script with the JavaScript code.

```
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

```

Import the selected [editor type](#ckeditor5/latest/getting-started/setup/editor-types.html) and plugins. The included script exposes the global variable named `CKEDITOR`. You can use object destructuring, shown below, to access the editor class and plugins.

```
const {
    ClassicEditor,
    Essentials,
    Bold,
    Italic,
    Font,
    Paragraph
} = CKEDITOR;

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
        ],
        root: {
            placeholder: 'Type here...'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Lastly, add a tag for the editor to attach to. Ensure the query selector matches the HTML element ID (or class).

```
<div id="editor">
    <p>Hello from CKEditor 5!</p>
</div>

```

A simple HTML page with the CKEditor may look like the one below.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 - Quick start CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>

        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

        <script>
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ],
                    root: {
                        placeholder: 'Type here...'
                    }
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-premium-features-from-cdn">

### Installing premium features from CDN

Just like with open-source features, start by attaching a link to style sheets. They contain all styles for the editor’s UI and content. The styles are in two separate style sheets – for open-source and premium plugins. You can also include your styles if you like. Refer to the [content styles](#ckeditor5/latest/getting-started/setup/css.html--styling-the-published-content) guide for more information.

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

```

Then, you need to attach the script tags with the JavaScript code. Similar to style sheets, there are separate scripts for open-source and premium plugins.

```
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>

<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>

```

Both included scripts expose global variables named `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES`. You can use object destructuring, shown below, to access the editor class and plugins. Open-source and premium features are in the respective global variables.

```
<script>
    const {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Font,
        Paragraph
    } = CKEDITOR;
    const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

Lastly, add a tag for the editor to attach to. Ensure the query selector matches the HTML element ID (or class).

```
<div id="editor">
    <p>Hello from CKEditor 5!</p>
</div>

```

A simple HTML page with the CKEditor may look like the one below.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 - Quick start CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>

        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>

        <script>
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;
            const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                        'formatPainter'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--obtaining-a-premium-features-license-key">

#### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--advanced-setup-with-import-maps">

### Advanced setup with import maps

To simplify imports, you can use the feature available in browsers – the [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap). It allows us to map an easy-to-remember specifier (like `ckeditor5` or `ckeditor5-premium-features`) to the full URL of the file from the CDN. We use this browser feature to share an editor engine code between plugins. Open source and premium plugins have their respective specifiers. Add mapping for premium features only if you use them.

```
<script type="importmap">
    {
        "imports": {
            "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
            "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",
            "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.js",
            "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/"
        }
    }
</script>

```

Once you have added the import map, you can access the editor and its plugins using the defined specifiers. Now, you can use standard ESM imports from the `ckeditor5` and `ckeditor5-premium-features` packages, like `import { ClassicEditor } from 'ckeditor5';`. Please note that to use premium features, you need to activate them with a proper license key, as mentioned in the [Obtaining a license key](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html--obtaining-a-premium-features-license-key) section.

In the following script tag, import the desired plugins and add them to the `plugins` array, and add toolbar items where applicable. Note that both script tags (this and the previous) have the appropriate `type` values.

```
<script type="module">
    import {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Font,
        Paragraph
    } from 'ckeditor5';
    import { FormatPainter } from 'ckeditor5-premium-features';

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|', 'formatPainter'
            ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

Your final page should look similar to the one below.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 - Quick start CDN</title>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    </head>
    <body>
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>

        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
                    "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",
                    "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.js",
                    "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/"
                }
            }
        </script>

        <script type="module">
            import {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } from 'ckeditor5';
            import { FormatPainter } from 'ckeditor5-premium-features';

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|', 'formatPainter'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--additional-setup-for-vite">

#### Additional setup for Vite

If you use UMD imports, you do not need to use any bundler. However, if your tooling enforces a Vite bundler or for some other reason you need one, follow the next steps.

Due to Vite limitations, using it with the cloud version of CKEditor 5 and ESM imports requires additional configuration. Vite does not fully support native import maps and external ESM modules (see [Vite Issue #6582](https://github.com/vitejs/vite/issues/6582)). Vite resolves imports at build time. Importing the editor using standard ESM syntax may force Vite to fall back to the UMD bundle, or it may cause errors.

To solve this issue, we can add a custom Vite plugin that externalizes CKEditor imports. This way, they can be resolved at runtime by the browser’s import map instead of being processed by Vite’s bundler. Below is the code of this plugin.

```
export function viteCKEditorExternalize() {
    return {
        name: 'ckeditor5-externalize',
        enforce: 'pre',
        config: ( config ) => {
            if ( config.optimizeDeps?.exclude && !Array.isArray( config.optimizeDeps.exclude ) ) {
                throw new Error( 'ckeditor5-externalize: config.optimizeDeps.exclude is not an array' );
            }

            if ( config.build?.rollupOptions?.external && !Array.isArray( config.build.rollupOptions.external ) ) {
                throw new Error( 'ckeditor5-externalize: config.build.rollupOptions.external is not an array' );
            }

            config.optimizeDeps ??= {};
            config.optimizeDeps.exclude = [
                ...( ( config.optimizeDeps.exclude ?? [] ) ),
                'ckeditor5',
                'ckeditor5-premium-features'
            ];

            config.build ??= {};
            config.build.rollupOptions ??= {};
            config.build.rollupOptions.external = [
                ...( ( config.build.rollupOptions.external ?? [] ) ),
                'ckeditor5',
                'ckeditor5-premium-features',
                /^ckeditor5\/.*/,
                /^ckeditor5-premium-features\/.*/
            ];
        },
        configResolved: ( resolvedConfig ) => {
            ( resolvedConfig.plugins ).push( {
                name: 'remove-id-prefix',
                transform: ( code ) => {
                    if ( typeof code === 'string' ) {
                        return code.replace( /\/@id\/ckeditor5/g, 'ckeditor5' );
                    }
                    return null;
                }
            } );
        },
        resolveId: ( id ) => {
            if (
                id === 'ckeditor5' ||
                id === 'ckeditor5-premium-features' ||
                id.startsWith( 'ckeditor5/' ) ||
                id.startsWith( 'ckeditor5-premium-features/' )
            ) {
                return {
                    id,
                    external: true
                };
            }
            return null;
        }
    };
}

```

You need to add the plugin to the `plugins` array in the Vite config to use it in your project.

```
// vite.config.js
import { viteCKEditorExternalize } from './plugins/vite-ckeditor-externalize.js';

export default {
    plugins: [ viteCKEditorExternalize() ]
};

```

The workaround should solve the issue and ensure a unified ESM development experience. Using this plugin, you can write clean ESM integration code regardless of the distribution channel.

<a id="ckeditor5/latest/getting-started/installation/cloud/quick-start.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html">source file: "ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html"</a>

## Integrating CKEditor 5 with React from CDN

CKEditor 5 has an official React integration that you can use to add a rich text editor to your application. This guide will help you install it and configure to use the CDN distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--quick-start">

### Quick start

This guide assumes that you already have a React project. If you do not have one, see the [React documentation](https://react.dev/learn/start-a-new-react-project) to learn how to create it.

Start by installing the React integration for CKEditor 5 from npm:

```
npm install @ckeditor/ckeditor5-react

```

Once the integration is installed, create a new React component called `Editor.jsx`. It will use the `useCKEditorCloud` helper to load the editor code from the CDN and the `<CKEditor>` component to run it, both of which come from the above package. The following example shows a component with open source and premium CKEditor 5 plugins.

```
import React from 'react';
import { CKEditor, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

const CKEditorDemo = () => {
    const cloud = useCKEditorCloud( {
        version: '48.0.0',
        premium: true
    } );

    if ( cloud.status === 'error' ) {
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const {
        ClassicEditor,
        Essentials,
        Paragraph,
        Bold,
        Italic
    } = cloud.CKEditor;

    const { FormatPainter } = cloud.CKEditorPremiumFeatures;

    return (
        <CKEditor
            editor={ ClassicEditor }
            data={ '<p>Hello world!</p>' }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
            } }
        />
    );
};

```

In the above example, the `useCKEditorCloud` helper is used to load the editor code and plugins from CDN. The `premium` option is set to also load premium plugins. For more information about the `useCKEditorCloud` helper, see the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--component-properties">

### Component properties

The `<CKEditor>` component supports the following properties:

* `editor` (required) – The [Editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) constructor to use.
* `data` – The initial data for the created editor. See the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* `config` – The editor configuration. See the [Configuration](#ckeditor5/latest/getting-started/setup/configuration.html) guide.
* `id` – The editor ID. When this property changes, the component restarts the editor with new data instead of setting it on an initialized editor.
* `disabled` – A Boolean value. The [editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) is being switched to read-only mode if the property is set to `true`.
* `disableWatchdog` – A Boolean value. If set to `true`, [the watchdog feature](#ckeditor5/latest/features/watchdog.html) will be disabled. It is set to `false` by default.
* `watchdogConfig` – [Configuration object](../../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) for the [watchdog feature](#ckeditor5/latest/features/watchdog.html).
* `onReady` – A function called when the editor is ready with an [editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) instance. This callback is also called after the reinitialization of the component if an error occurred.
* `onAfterDestroy` – A function called after the successful destruction of an editor instance rendered by the component. This callback is also triggered after the editor has been reinitialized after an error. The component is not guaranteed to be mounted when this function is called.
* `onChange` – A function called when the editor data has changed. See the [editor.model.document#change:data](../../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.
* `onBlur` – A function called when the editor was blurred. See the [editor.editing.view.document#blur](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.
* `onFocus` – A function called when the editor was focused. See the [editor.editing.view.document#focus](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.
* `onError` – A function called when the editor has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:
* `phase`: `'initialization'|'runtime'` – Informs when the error has occurred (during or after the editor/context initialization).
* `willEditorRestart` – When `true`, it means the editor component will restart itself.

The editor event callbacks (`onChange`, `onBlur`, `onFocus`) receive two arguments:

1. An [EventInfo](../../../../api/module%5Futils%5Feventinfo-EventInfo.html) object.
2. An [Editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) instance.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--context-feature">

### Context feature

The [@ckeditor/ckeditor5-react](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) package provides a ready-to-use component for the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html) that is useful to use with some [CKEditor 5 collaboration features](#ckeditor5/latest/features/collaboration/collaboration.html).

```
import React from 'react';
import { CKEditor, CKEditorContext, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

export const CKEditorCloudContextDemo = () => {
    const cloud = useCKEditorCloud( {
        version: '48.0.0'
    } );

    if ( cloud.status === 'error' ) {
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const { ClassicEditor } = cloud.CKEditor;

    return (
        <CKEditorContext
            context={ ClassicEditor.Context }
            contextWatchdog={ ClassicEditor.ContextWatchdog }
            onChangeInitializedEditors={ editors => {
                console.log( 'Initialized editors:', editors );
            } }
        >
            <CKEditorNestedInstanceDemo
                name='editor1'
                content='<p>Editor 1</p>'
            />

            <br />

            <CKEditorNestedInstanceDemo
                name='editor2'
                content='<p>Editor 2</p>'
            />
        </CKEditorContext>
    );
};

function CKEditorNestedInstanceDemo( { name, content } ) {
    const cloud = useCKEditorCloud( {
        version: '48.0.0',
        premium: true
    } );

    if ( cloud.status === 'error' ) {
        console.error( cloud );
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const {
        ClassicEditor,
        Essentials,
        Paragraph,
        Bold,
        Italic,
        Mention
    } = cloud.CKEditor;

    return (
        <CKEditor
            contextItemMetadata={ {
                name
            } }
            editor={ ClassicEditor }
            data={ content }
            config={ {
                plugins: [
                    Essentials,
                    Paragraph,
                    Bold,
                    Italic,
                    Mention
                ],
                toolbar: {
                    items: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                }
            } }
        />
    );
}

```

The `CKEditorContext` component supports the following properties:

* `context` (required) – [The CKEditor 5 context class](../../../../api/module%5Fcore%5Fcontext-Context.html).
* `contextWatchdog` (required) – [The Watchdog context class](../../../../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html).
* `config` – The CKEditor 5 context configuration.
* `isLayoutReady` – A property that delays the context creation when set to `false`. It creates the context and the editor children once it is `true` or unset. Useful when the CKEditor 5 annotations or a presence list are used.
* `id` – The context ID. When this property changes, the component restarts the context with its editor and reinitializes it based on the current configuration.
* `onChangeInitializedEditors` – A function called when any editor is initialized or destroyed in the tree. It receives a dictionary of fully initialized editors, where the key is the value of the `contextItemMetadata.name` property set on the `CKEditor` component. The editor’s ID is the key if the `contextItemMetadata` property is absent. Additional data can be added to the `contextItemMetadata` in the `CKEditor` component, which will be passed to the `onChangeInitializedEditors` function.
* `onReady` – A function called when the context is ready and all editors inside were initialized with the `context` instance. This callback is also called after the reinitialization of the component if an error has occurred.
* `onError` – A function called when the context has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:
* `phase`: `'initialization'|'runtime'` – Informs when the error has occurred (during or after the editor/context initialization).
* `willContextRestart` – When `true`, it means that the context component will restart itself.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--using-the-document-editor-type">

#### Using the document editor type

If you use the [document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html), you need to [add the toolbar to the DOM manually](../../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create):

```
import { useEffect, useRef, useState } from 'react';
import { CKEditor } from '@ckeditor/ckeditor5-react';

function App() {
    const cloud = useCKEditorCloud( {
        version: '48.0.0'
    } );

    const editorToolbarRef = useRef( null );
    const [ isMounted, setMounted ] = useState( false );

    useEffect( () => {
        setMounted( true );

        return () => {
            setMounted( false );
        };
    }, [] );

    if ( cloud.status === 'error' ) {
        console.error( cloud );
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const { DecoupledEditor, Essentials, Paragraph, Bold, Italic } = cloud.CKEditor;

    return (
        <div>
            <div ref={ editorToolbarRef }></div>
            <div>
                { isMounted && (
                    <CKEditor
                        editor={ DecoupledEditor }
                        data='<p>Hello from CKEditor 5 decoupled editor!</p>'
                        config={ {
                            plugins: [ Essentials, Paragraph, Bold, Italic ],
                            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
                        } }
                        onReady={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                editorToolbarRef.current.appendChild( editor.ui.view.toolbar.element );
                            }
                        }}
                        onAfterDestroy={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                Array.from( editorToolbarRef.current.children ).forEach( child => child.remove() );
                            }
                        } }
                    />
                ) }
            </div>
        </div>
    );
}

export default App;

```

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a few **ready-to-use integrations** featuring collaborative editing in React applications:

* [CKEditor 5 with real-time collaboration features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-react)
* [CKEditor 5 with real-time collaboration and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-revision-history-for-react)
* [CKEditor 5 with the revision history feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/revision-history-for-react)
* [CKEditor 5 with the track changes feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/track-changes-for-react)

It is not mandatory to build applications on top of the above samples, however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official React component. To translate the editor, pass the languages you need into the `translations` array inside the configuration of the `useCKEditorCloud` hook.

```
import React from 'react';
import { CKEditor, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

const CKEditorDemo = () => {
    const cloud = useCKEditorCloud( {
        version: '48.0.0',
        translations: [ 'es' ]
    } );

    if ( cloud.status === 'error' ) {
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Paragraph
    } = cloud.CKEditor;

    return (
        <CKEditor
            editor={ ClassicEditor }
            data={ '<p>Hello world!</p>' }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                plugins: [ Bold, Essentials, Italic, Paragraph ],
            } }
        />
    );
};

```

For more information, please refer to the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--typescript-support">

#### TypeScript support

The official React integration for CKEditor 5 is written in TypeScript and fully supports it. If you use TypeScript in your project, you can use the `CKEditor` component without additional configuration. However, if you want to use some specific types from the CKEditor 5 packages, you can import them directly from a special package containing type definitions. Take a look at the following example:

```
import React from 'react';
import { CKEditor, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

import type { EventInfo } from 'https://cdn.ckeditor.com/typings/ckeditor5.d.ts';

const CKEditorDemo = () => {
    const cloud = useCKEditorCloud( {
        version: '48.0.0',
        translations: [ 'es' ]
    } );

    if ( cloud.status === 'error' ) {
        return <div>Error!</div>;
    }

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    const {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Paragraph
    } = cloud.CKEditor;

    return (
        <CKEditor
            editor={ ClassicEditor }
            data={ '<p>Hello world!</p>' }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                plugins: [ Bold, Essentials, Italic, Paragraph ],
            } }
            onBlur={ ( event: EventInfo ) => {
                // your event handler
            } }
        />
    );
};

```

In the example above, the `EventInfo` type is imported from the `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` package, while the editor itself loads from the CDN. Note that `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` is not an actual URL to the CKEditor 5 typings file but a synthetic TypeScript module providing typings for the editor. The `ckeditor5` package supplies the actual types, which depend on the `@ckeditor/ckeditor5-react` package.

Although this setup might seem complex, it prevents users from directly importing anything from the `ckeditor5` package, which could lead to duplicated code issues.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--type-definitions-for-premium-features">

##### Type definitions for premium features

If you want to use types for premium features, you can import them similarly to the base editor types. Remember that you need to install the `ckeditor5-premium-features` package to use them. You can do it by running the following command:

```
npm install --save-dev ckeditor5-premium-features

```

After installing the package, you can import the types in the following way:

```
<script setup>
// ...
import type { Mention } from 'https://cdn.ckeditor.com/typings/ckeditor5-premium-features.d.ts';
// ...
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--known-issues">

### Known issues

While type definitions for the base editor should be available out of the box, some bundlers do not install the `ckeditor5` package, which provides typing for the editor. If you encounter any issues with the type definitions, you can install the `ckeditor5` package manually:

```
npm install --save-dev ckeditor5

```

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of rich text editor component for React is available on GitHub in <https://github.com/ckeditor/ckeditor5-react>.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html">source file: "ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html"</a>

## Integrating CKEditor 5 with React multi-root editor hook from CDN

This page focuses on describing the usage of the multi-root editor in React applications. If you would like to use a different type of editor, you can find more information [in this guide](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--quick-start">

### Quick start

This guide assumes you already have a React project. If you want to create a new one, you can use the [Vite](https://vitejs.dev/guide/) CLI. It allows you to create and customize your project with templates. For example, you can set up your project with TypeScript support.

Install the [CKEditor 5 WYSIWYG editor package for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) and the [multi-root editor type](#ckeditor5/latest/getting-started/setup/editor-types.html--multi-root-editor).

```
npm install ckeditor5 @ckeditor/ckeditor5-react

```

Use the `useMultiRootEditor` hook inside your project:

```
import React from "react";
import { useMultiRootEditor, withCKEditorCloud } from "@ckeditor/ckeditor5-react";

const withCKCloud = withCKEditorCloud( {
    cloud: {
        version: "48.0.0",
        languages: [ "es" ],
        premium: true,
    },

    // Optional:
    renderError: ( error ) => <div>Error!</div>,

    // Optional:
    renderLoader: () => <div>Loading...</div>,
} );

const MultiRootEditorDemo = withCKCloud(
    ( { data, cloud } ) => {
        const {
            MultiRootEditor: MultiRootEditorBase,
            Essentials,
            Paragraph
            Bold,
            Italic
        } = cloud.CKEditor;

        const { FormatPainter } = cloud.CKEditorPremiumFeatures;

        class MultiRootEditor extends MultiRootEditorBase {
            static builtinPlugins = [
                Essentials,
                Paragraph,
                Bold,
                Italic,
                FormatPainter
            ];

            static defaultConfig = {
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
            };
        }

        const { toolbarElement, editableElements } = useMultiRootEditor( {
            editor: MultiRootEditor,
            data,
        } );

        return (
            <div>
                { toolbarElement }
                { editableElements }
            </div>
        );
    }
);

```

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--hook-properties">

### Hook properties

The `useMultiRootEditor` hook supports the following properties:

* `editor: MultiRootEditor` (required) – The [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) constructor to use.
* `data: Object` – The initial data for the created editor. See the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* `rootsAttributes: Object` – The initial roots attributes for the created editor.
* `config: Object` – The editor configuration. See the [Configuration](#ckeditor5/latest/getting-started/setup/configuration.html) guide.
* `disabled: Boolean` – The [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) is being switched to read-only mode if the property is set to `true`.
* `disableWatchdog: Boolean` – If set to `true`, [the watchdog feature](#ckeditor5/latest/features/watchdog.html) will be disabled. It is set to `false` by default.
* `watchdogConfig: WatchdogConfig` – [Configuration object](../../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) for the [watchdog feature](#ckeditor5/latest/features/watchdog.html).
* `isLayoutReady: Boolean` – A property that delays the editor creation when set to `false`. It starts the initialization of the multi-root editor when sets to `true`. Useful when the CKEditor 5 annotations or a presence list are used.
* `disableTwoWayDataBinding: Boolean` – Allows disabling the two-way data binding mechanism between the editor state and `data` object to improve editor efficiency. The default value is `false`.
* `onReady: Function` – It is called when the editor is ready with a [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) instance. This callback is also called after the reinitialization of the component if an error occurred.
* `onChange: Function` – It is called when the editor data has changed. See the [editor.model.document#change:data](../../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.
* `onBlur: Function` – It is called when the editor was blurred. See the [editor.editing.view.document#blur](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.
* `onFocus: Function` – It is called when the editor was focused. See the [editor.editing.view.document#focus](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.
* `onError: Function` – It is called when the editor has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details.  
Error details is an object that contains two properties:  
  * `phase: 'initialization'|'runtime'` – Informs when an error has occurred (during the editor or context initialization, or after the initialization).
  * `willEditorRestart: Boolean` – If set to `true`, the editor component will restart itself.

The editor event callbacks (`onChange`, `onBlur`, `onFocus`) receive two arguments:

1. An [EventInfo](../../../../api/module%5Futils%5Feventinfo-EventInfo.html) object.
2. An [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) instance.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--hook-values">

### Hook values

The `useMultiRootEditor` hook returns the following values:

* `editor` – The instance of created editor.
* `toolbarElement` – `ReactElement` that contains the toolbar. It could be rendered anywhere in the application.
* `editableElements` – An array of `ReactElements` that describes the editor’s roots. This array is updated after detaching an existing root or adding a new root.
* `data` – The current state of the editor’s data. It is updated after each editor update. Note that you should not use it if you disabled two-way binding by passing the `disableTwoWayDataBinding` property.
* `setData` – The function used for updating the editor’s data.
* `attributes` – The current state of the editor’s attributes. It is updated after each editor attributes update. Note that you should not use it if you disabled two-way binding by passing the `disableTwoWayDataBinding` property.
* `setAttributes` – The function used for updating the editor’s attributes.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--context-feature">

### Context feature

The `useMultiRootEditor` hook also supports the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html), as described in the main [React integration](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--context-feature) guide.

However, as the multi-root editor addresses most use cases of the context feature, consider if you need to employ it.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--two-way-data-binding">

### Two-way data binding

By default, the two-way data binding is enabled. It means that every change done in the editor is automatically applied in the `data` object returned from the `useMultiRootEditor` hook. Additionally, if you want to change or set data in the editor, you can simply use `setData` method provided by the hook. It works the same way in case of attributes – the hook provides the `attributes` object and the `setAttributes` method to update them. It ensures that if you want to use or save the state of the editor, these objects are always up-to-date.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of rich text editor component for React is available on GitHub in <https://github.com/ckeditor/ckeditor5-react>.

<a id="ckeditor5/latest/getting-started/installation/cloud/react/react-multiroot-cdn.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html">source file: "ckeditor5/latest/getting-started/installation/cloud/salesforce.html"</a>

## Integrating CKEditor 5 with Salesforce from CDN

Salesforce is a cloud-based Customer Relationship Management (CRM) platform that enables organizations to manage customer interactions, sales processes, and business operations. The platform supports custom development through its Lightning Platform (formerly Force.com), allowing developers to create custom objects, fields, pages, and components. While [CKEditor 5 does not support Shadow DOM yet](https://github.com/ckeditor/ckeditor5/issues/3891), which is required by Lightning modules, it can be integrated into Salesforce using [Visualforce pages](https://help.salesforce.com/s/articleView?id=platform.pages%5Fpages.htm&type=5). This integration approach enables rich text editing capabilities within Salesforce applications.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--prerequisites">

### Prerequisites

This section assumes you are working within the [Salesforce development platform](https://www.salesforce.com/form/developer-signup). We will guide you through creating a new Visualforce page that incorporates CKEditor 5\. Visualforce pages provide a way to create custom user interfaces in Salesforce using a markup language similar to HTML, making it an ideal solution for integrating third-party components like CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--creating-a-visualforce-page">

### Creating a Visualforce page

To start the integration, you need to create a new Visualforce page that will be used for the CKEditor 5 integration. Navigate to the _Setup_ page of your development platform and use the search input to find _Visualforce pages_.

Enter the Visualforce pages tab and add a new page by clicking the _New_ button. You should see a form that allows adding new pages, along with a code editor containing the default page markup.

Fill out the required fields in the form, check the _Available for Lightning Experience, Experience Builder sites, and the mobile app_ checkbox, then save the page. You are now ready to integrate the editor.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--integrating-ckeditor-5-in-visualforce-page-using-cdn">

### Integrating CKEditor 5 in Visualforce page using CDN

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--setting-up-the-page-structure">

#### Setting up the page structure

Visualforce pages use a markup language similar to HTML, but with special tags prefixed with `apex:`. Every Visualforce page must be wrapped in an `<apex:page>` tag, which serves as the root element. This tag can include various attributes to control the page’s behavior, such as `docType`, `showHeader`, and `standardStylesheets`. Inside this wrapper, you can use standard HTML elements along with Visualforce-specific components to build your page layout and functionality.

For our CKEditor 5 integration, we will use a basic page structure that includes necessary JavaScript and CSS resources, along with a container for the editor. The page markup will look similar to this:

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Resources will be added here -->
    </head>
    <body>
        <!-- Editor container will be added here -->
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--adding-ckeditor-5-resources">

#### Adding CKEditor 5 resources

We will start from adding resources required for running CKEditor 5 (CSS and JavaScript) to the `<head>` tag. However, before we do it, make sure to add `https://cdn.ckeditor.com` domain to [Trusted URLs](https://help.salesforce.com/s/articleView?id=xcloud.security%5Ftrusted%5Furls%5Fmanage.htm&type=5):

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Load your editor's JavaScript and CSS from the CDN -->
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

        <!-- Add if you use premium features. -->
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    </head>
    <body>
        <!-- Editor container will be added here -->
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--initializing-the-editor">

#### Initializing the editor

Now, we can add the container that will hold our editor and introduce an initialization script with the basic editor configuration:

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- JavaScript and CSS resources-->
    </head>
    <body>
        <!-- Editor container -->
         <div id="editor" style="min-height: 300px; border: 1px solid #ccc;"></div>

         <!-- Initialization script -->
          <script>
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;
            const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                        'formatPainter'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
       </script>
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--complete-integration-code">

#### Complete integration code

Putting everything together, the full integration code looks as follows (remember to insert your license key in the editor configuration):

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Load your editor's JavaScript and CSS from the CDN -->
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

        <!-- Add if you use premium features. -->
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    </head>
    <body>
        <!-- Editor container -->
         <div id="editor" style="min-height: 300px; border: 1px solid #ccc;">CKEditor&nbsp;5 integration with Salesforce.</div>

         <!-- Initialization script -->
          <script>
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;
            const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                        'formatPainter'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</apex:page>

```

Now, you can save your component and click the _Preview_ button to see it live. A new page should open in your browser, and you should see the CKEditor 5 instance:

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--using-ckeditor-5-visualforce-component-in-lightning-page">

### Using CKEditor 5 Visualforce component in Lightning page

Now that we have created our CKEditor 5 Visualforce page, we can embed it into a Lightning page. This process involves adding the Visualforce page as a component within your Lightning page layout. To do this, navigate to the Lightning App Builder, where you can drag and drop the Visualforce page component onto your desired location in the page layout. The editor will be displayed within an iframe, maintaining its full functionality while being seamlessly integrated into your Lightning page.

Let’s go through the steps to add our CKEditor 5 component to a Lightning page:

To add your CKEditor 5 component to a Lightning page, first navigate to the Lightning App Builder. Once there, either select an existing Lightning page or create a new one where you want to incorporate the editor. Next, locate the Visualforce page component in the components panel and add it to your desired position in the layout. After adding the component, configure its settings and specifically select your CKEditor 5 component from the available options. Finally, save your changes and activate the Lightning page to make it available to users.

You should end up with something similar to this:

Now, you can view your Lightning page and use your editor:

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--distributing-your-ckeditor-5-component">

### Distributing your CKEditor 5 component

To make your CKEditor 5 Visualforce component available to other Salesforce users, you can create a package. This allows you to distribute your component as a standalone solution that can be easily installed in other Salesforce environments.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--creating-a-package">

#### Creating a package

To create a package, navigate to the Salesforce Setup page and use the Quick Find box to search for _Packages_. Click the “New” button to start creating your package. In the package creation form, provide a meaningful name like “CKEditor 5 Integration” and a clear description that explains the purpose of your component. Set the initial version to “1.0” and consider selecting “Managed Package” if you want to maintain control over future updates. This option allows you to push updates to all installations of your package.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--adding-components-to-the-package">

#### Adding components to the package

After creating the package, you will need to add your CKEditor 5 Visualforce page to it. In the package details page, use the “Add” button to include new components. Select “Visualforce Page” from the component type dropdown and choose your CKEditor 5 Visualforce page from the list. This will include all the necessary code and resources in your package.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--uploading-the-package">

#### Uploading the package

Once you have added all required components, you can upload your package. The upload process involves choosing whether to make the package public or private. Public packages are visible in the Salesforce AppExchange, while private packages are only accessible via direct installation links. After selecting the visibility option and accepting the terms and conditions, click _Upload_ to make your package available for distribution.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--installing-the-package">

#### Installing the package

After the upload is complete, you will receive an installation URL that looks like this:

```
https://login.salesforce.com/packaging/installPackage.apexp?p0=04td20000002WVF&isdtp=p1

```

Users can install your package by logging into their Salesforce account and visiting this URL. The installation process will guide them through granting necessary permissions and configuring the component in their environment.

After installation, users can add the CKEditor 5 component to their Lightning pages following the steps described in the [Using CKEditor 5 Visualforce component in Lightning page](#ckeditor5/latest/getting-started/installation/cloud/salesforce.html--using-ckeditor-5-visualforce-component-in-lightning-page) section.

<a id="ckeditor5/latest/getting-started/installation/cloud/salesforce.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html">source file: "ckeditor5/latest/getting-started/installation/cloud/spring-boot.html"</a>

## Integrating CKEditor 5 with Spring Boot from CDN

As a pure JavaScript/TypeScript library, CKEditor 5 rich-text editor will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 in a non-JS framework of your choice, for example, the Java-based [Spring Boot](https://spring.io/projects/spring-boot).

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Spring Boot project. You can create a basic Spring Boot project using [Spring Initializr](https://start.spring.io/). Refer to the [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html) to learn how to set up a project in this framework.

This guide is using the “Spring Web” and “Thymeleaf” dependencies selected in the Spring Initializr. Here is the list of dependencies used in the demo project:

```
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
</dependencies>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html--project-structure">

### Project structure

The folder structure of the created project should resemble the one below:

```
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           └── demo
│   │   │               └── DemoApplication.java
│   │   └── resources
│   │       ├── static
│   │       │   └── ...
│   │       ├── templates
│   │       │   ├── index.html
│   │       │   └── ...
│   │       └── application.properties
│   └── test
├── pom.xml
└── ...

```

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html--adding-ckeditor-5-container-scripts-and-styles">

### Adding CKEditor 5 container, scripts and styles

First, create or modify the `index.html` file in the `src/main/resources/templates` directory to include the CKEditor 5 scripts and styles. All necessary scripts and links are in the HTML snippet below. You can copy and paste them into your template. Open-source and premium features are in separate files, so there are different tags for both types of plugins. Add tags for premium features only if you use them.

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 - Spring Boot CDN Integration</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
    .main-container {
        width: 795px;
        margin-left: auto;
        margin-right: auto;
    }
    </style>
</head>
<body>
    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>
</body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html--adding-the-editor-creation-script">

### Adding the Editor creation script

Both previously attached scripts expose global variables named `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES`. You can use them to access the editor class and plugins. In our example, we use object destructuring (a JavaScript feature) to access the editor class from the open-source global variable with a basic set of plugins. You can access premium plugins from the other variable the same way. Then, we pass the whole configuration to the `create()` method. Be aware that you need a proper [license key](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) to use the integration.

```
<script>
    const {
        ClassicEditor,
        Essentials,
        Bold,
        Italic,
        Font,
        Paragraph
    } = CKEDITOR;
    const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ]
        } )
        .then( /* ... */ )
        .catch( /* ... */ );
</script>

```

Now, we need to put our script in the previous template. We need to put the script under the `<div>` element, so the editor can attach to it. Your final template should look like this:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 - Spring Boot CDN Integration</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.umd.js"></script>
    <!-- Add if you use premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/43.0.0/ckeditor5-premium-features.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/43.0.0/ckeditor5-premium-features.umd.js"></script>
    <!--  -->
    <style>
        .main-container {
            width: 795px;
            margin-left: auto;
            margin-right: auto;
        }
    </style>
</head>
<body>
    <div class="main-container">
        <div id="editor">
            <p>Hello from CKEditor 5!</p>
        </div>
    </div>
    <script>
        const {
            ClassicEditor,
            Essentials,
            Bold,
            Italic,
            Font,
            Paragraph
        } = CKEDITOR;
        const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

        ClassicEditor
            .create( {
                attachTo: document.querySelector( '#editor' ),
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
                toolbar: [
                    'undo', 'redo', '|', 'bold', 'italic', '|',
                    'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                    'formatPainter'
                ]
            } )
            .then( editor => {
                window.editor = editor;
            } )
            .catch( error => {
                console.error( error );
            } );
    </script>
</body>
</html>

```

To make the HTML editor work with Spring Boot, you need to create a controller to serve the HTML page. Create a file named `HomeController.java` in your project’s main package:

```
package com.example.demo;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/")
    public String home() {
        return "index";
    }
}

```

Finally, run your Spring Boot application using `./mvnw spring-boot:run` (or `mvnw.cmd spring-boot:run` on Windows) and navigate to `http://localhost:8080` to see the editor in action.

<a id="ckeditor5/latest/getting-started/installation/cloud/spring-boot.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html">source file: "ckeditor5/latest/getting-started/installation/cloud/svelte.html"</a>

## Integrating CKEditor 5 with Svelte from CDN

[Svelte](https://svelte.dev/) is a modern JavaScript compiler that builds highly optimized, reactive web applications. Unlike traditional frameworks, Svelte shifts most of the work from runtime to build time, resulting in highly efficient applications. CKEditor 5 rich-text editor can be easily integrated with Svelte applications, providing powerful rich text editing capabilities to your projects.

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--quick-start">

### Quick start

This guide will show you how to integrate CKEditor 5 into a Svelte application using the CDN distribution. If you are new to Svelte, check out their [official tutorial](https://svelte.dev/docs/svelte/getting-started).

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--setting-up-a-svelte-project">

#### Setting up a Svelte project

First, create a new Svelte project using Vite:

```
npm create vite@latest ckeditor-svelte -- --template svelte
cd ckeditor-svelte
npm install

```

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--project-structure">

#### Project structure

When completed, the folder structure of your project should resemble this one:

```
├── node_modules/
├── public/
├── src/
│   ├── lib/
│   │   └── Editor.svelte
│   ├── App.svelte
│   ├── main.js
│   └── ...
├── index.html
├── package.json
├── vite.config.js
├── svelte.config.js
└── ...

```

The integration requires:

* Modifying `index.html` to include CKEditor 5 scripts and style sheets
* Creating the `src/lib/Editor.svelte` component
* Updating the `src/App.svelte` main application component

Let’s implement these changes next.

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--adding-ckeditor-5-scripts-and-styles">

#### Adding CKEditor 5 scripts and styles

To load CKEditor 5 from CDN, modify the main HTML file of your project (`index.html`) to include the necessary scripts and style sheets:

```
<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 + Svelte</title>
        <!-- CKEditor 5 CSS -->
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
        <!-- CKEditor 5 Scripts -->
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    </head>
    <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
    </body>
</html>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--implementing-the-editor-component">

#### Implementing the Editor component

Create a new file `src/lib/Editor.svelte` with the following content:

```
<script>
    import { onMount, onDestroy } from 'svelte';

    let { value = $bindable('') } = $props();

    let editorContainer;
    let editorInstance = $state(null);
    let isDestroyed = false;

    // Sync external value changes to the editor.
    $effect(() => {
        if (editorInstance && editorInstance.getData() !== value) {
            editorInstance.setData(value);
        }
    });

    onMount( async () => {
        const { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } = CKEDITOR;
        const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

        // Capture value before async initialization.
        let initialData = value;

        editorInstance = await ClassicEditor.create( {
            attachTo: editorContainer,
            licenseKey: '<YOUR_LICENSE_KEY>', // Replace with your license key
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ],
            initialData
        } );

        // Prevent memory leaks if unmounted during creation.
        if (isDestroyed) {
            await editorInstance.destroy();
            return;
        }

        // Update the bound value when editor content changes.
        editorInstance.model.document.on( 'change:data', () => {
            value = editorInstance.getData();
        } );
    } );

    onDestroy( () => {
        // Clean up editor instance on unmount.
        editorInstance?.destroy().catch( err => console.error( err ) );
        editorInstance = null;
        isDestroyed = true;
    } );
</script>

<div bind:this={editorContainer}></div>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--using-the-editor-component">

#### Using the Editor component

Now, modify the main `App.svelte` file to use our editor component:

```
<script>
    import Editor from './lib/Editor.svelte';

    let content = $state('<p>Enter your content here...</p>');
</script>

<main>
    <h1>CKEditor 5 + Svelte</h1>

    <div class="editor-wrapper">
        <Editor bind:value={content} />
    </div>
</main>

<style>
    .editor-wrapper {
        width: 800px;
    }

    :global(.ck.ck-editor__editable) {
        height: 200px;
        background-color: white;
        color: #333;
    }
</style>

```

You can now run the dev server to see the editor in action:

```
npm run dev

```

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--component-structure">

#### Component structure

The Svelte HTML editor integration follows these key steps:

1. **Static loading**: CKEditor 5 scripts and styles are loaded from CDN in the HTML file.
2. **Editor initialization**: The editor is created with the specified configuration when the component mounts.
3. **Two-way data binding**: The editor listens to `change:data` events on `editor.model.document` to update the bound value, while a Svelte `$effect` syncs external value changes back to the editor.
4. **Cleanup**: Resources are properly released when the component is destroyed.

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--styling">

#### Styling

Basic styling is provided in the `App.svelte` component to ensure proper display in various environments, especially when using dark themes:

```
.editor-wrapper {
    width: 800px;
}

:global(.ck.ck-editor__editable) {
    height: 200px;
    background-color: white;
    color: #333;
}

```

<a id="ckeditor5/latest/getting-started/installation/cloud/svelte.html--next-steps">

### Next steps

* Explore the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide to learn how to handle content.
* Learn more about [configuration options](#ckeditor5/latest/getting-started/setup/configuration.html) to customize your editor.
* Check the [features documentation](#ckeditor5/latest/features/index.html) to add more functionality to your editor.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html">source file: "ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html"</a>

## Integrating CKEditor 5 with Vue.js 2.x from CDN

You can use CKEditor 5 Vue 2 component to add a rich text editor to your application. This guide will help you install and configure the CDN distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--quick-start">

### Quick start

First, install the CKEditor 5 WYSIWYG editor component for Vue 2:

```
npm install @ckeditor/ckeditor5-vue2

```

Then, include the CKEditor 5 scripts and styles. All necessary scripts and links are shown in the HTML snippet below. You can copy and paste them into your `index.html` file. Open-source and premium features are in separate files, so there are different tags for both types of plugins. Add tags for premium features only if you use them.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />

        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <!-- Add if you use premium features -->
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>

        <title>CKEditor 5 - Vue 2</title>
    </head>
    <body>
        <div id="app"></div>
        <script type="module" src="/src/main.js"></script>
    </body>
</html>

```

To create an editor instance, you must first import the editor and the component modules into the root file of your application (for example, `main.js` when generated by create-vue).

```
import Vue from 'vue';
import CKEditor from '@ckeditor/ckeditor5-vue2';
import App from './App.vue';

Vue.use( CKEditor );

new Vue( App ).$mount( '#app' );

```

Use the `<ckeditor>` component inside the template tag. The below example shows how to use the component with open-source and premium plugins. To make it work, you need to provide a proper license key.

```
<template>
    <ckeditor :editor="editor" v-model="editorData" :config="editorConfig" />
</template>

<script>
const {
    ClassicEditor,
    Essentials,
    Bold,
    Italic,
    Paragraph,
} = CKEDITOR;
const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

export default {
    name: 'app',
    data() {
        return {
            editor: ClassicEditor,
            editorData: '<p>Hello from CKEditor 5 in Vue 2!</p>',
            editorConfig: {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
            }
        };
    }
};
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--component-directives">

### Component directives

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--editor">

#### `editor`

This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.

```
<template>
    <ckeditor :editor="editor" />
</template>

<script>
    const { ClassicEditor } = CKEDITOR;

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,

                // ...
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--tag-name">

#### `tag-name`

By default, the editor component creates a `<div>` container which is used as an element passed to the editor (for example, [ClassicEditor#element](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html#member-element)). The element can be configured, so for example to create a `<textarea>`, use the following directive:

```
<ckeditor :editor="editor" tag-name="textarea" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--v-model">

#### `v-model`

A [standard directive](https://vuejs.org/v2/api/#v-model) for form inputs in Vue. Unlike [value](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--value), it creates a two–way data binding, which:

* Sets the initial editor content.
* Automatically updates the state of the application as the editor content changes (for example, as the user types).
* Can be used to set the editor content when necessary.

```
<template>
    <div>
        <ckeditor :editor="editor" v-model="editorData" />
        <button v-on:click="emptyEditor()">Empty the editor</button>

        <h2>Editor data</h2>
        <code>{{ editorData }}</code>
    </div>
</template>

<script>
    const { ClassicEditor } = CKEDITOR;

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        },
        methods: {
            emptyEditor() {
                this.editorData = '';
            }
        }
    };
</script>

```

In the above example, the `editorData` property will be updated automatically as the user types and changes the content. It can also be used to change (as in `emptyEditor()`) or set the initial content of the editor.

If you only want to execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--value">

#### `value`

Allows a one–way data binding that sets the content of the editor. Unlike [v-model](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--v-model), the value will not be updated when the content of the editor changes.

```
<template>
    <ckeditor :editor="editor" :value="editorData" />
</template>

<script>
    const { ClassicEditor } = CKEDITOR;

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        }
    };
</script>

```

To execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--config">

#### `config`

Specifies the [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor.

```
<template>
    <ckeditor :editor="editor" :config="editorConfig" />
</template>

<script>
    const { ClassicEditor } = CKEDITOR;

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorConfig: {
                    toolbar: [ 'bold', 'italic', '|', 'link' ]
                }
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--disabled">

#### `disabled`

This directive controls the [isReadOnly](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property of the editor.

It sets the initial read–only state of the editor and changes it during its lifecycle.

```
<template>
    <ckeditor :editor="editor" :disabled="editorDisabled" />
</template>

<script>
    const { ClassicEditor } = CKEDITOR;

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                // This editor will be read–only when created.
                editorDisabled: true
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--component-events">

### Component events

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--ready">

#### `ready`

Corresponds to the [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) editor event.

```
<ckeditor :editor="editor" @ready="onEditorReady" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--focus">

#### `focus`

Corresponds to the [focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) editor event.

```
<ckeditor :editor="editor" @focus="onEditorFocus" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--blur">

#### `blur`

Corresponds to the [blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) editor event.

```
<ckeditor :editor="editor" @blur="onEditorBlur" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--input">

#### `input`

Corresponds to the [change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) editor event. See the [v-model directive](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--v-model) to learn more.

```
<ckeditor :editor="editor" @input="onEditorInput" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--destroy">

#### `destroy`

Corresponds to the [destroy](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-destroy) editor event.

**Note:** Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.

```
<ckeditor :editor="editor" @destroy="onEditorDestroy" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v2.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html">source file: "ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html"</a>

## Integrating CKEditor 5 with Vue.js 3+ from CDN

CKEditor 5 has an official Vue integration that you can use to add a rich text editor to your application. This guide will help you install it and configure to use the CDN distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--quick-start">

### Quick start

This guide assumes that you already have a Vue project. If you do not have one, see the [Vue documentation](https://vuejs.org/guide/quick-start) to learn how to create it.

Start by installing the Vue integration for CKEditor 5 from npm:

```
npm install @ckeditor/ckeditor5-vue

```

Once the integration is installed, create a new Vue component called `Editor.vue`. It will use the `useCKEditorCloud` helper to load the editor code from the CDN and the `<ckeditor>` component to run it, both of which come from the above package. The following example shows a single file component with open source and premium CKEditor 5 plugins.

```
<template>
    <ckeditor
        v-if="editor"
        v-model="data"
        :editor="editor"
        :config="config"
    />
</template>

<script setup>
import { ref, computed } from 'vue';
import { Ckeditor, useCKEditorCloud } from '@ckeditor/ckeditor5-vue';

const cloud = useCKEditorCloud( {
    version: '48.0.0',
    premium: true
} );

const data = ref( '<p>Hello world!</p>' );

const editor = computed( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    return cloud.data.value.CKEditor.ClassicEditor;
} );

const config = computed( () => {
        if ( !cloud.data.value ) {
        return null;
    }

    const { Essentials, Paragraph, Bold, Italic } = cloud.data.value.CKEditor;
    const { FormatPainter } = cloud.data.value.CKEditorPremiumFeatures;

    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    };
} );
</script>

```

In the above example, the `useCKEditorCloud` helper is used to load the editor code and plugins from CDN. The `premium` option is set to also load premium plugins. For more information about the `useCKEditorCloud` helper, see the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide.

Now, you can import and use the `Editor.vue` component anywhere in your application.

```
<template>
    <Editor />
</template>

```

If you use Nuxt.js with server-side rendering enabled, remember to wrap the `<Editor>` component in the `<ClientOnly>` component to avoid issues with the editor calling browser-specific APIs on the server.

```
<template>
    <ClientOnly>
        <Editor />
    </ClientOnly>
</template>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--component-directives">

### Component directives

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--editor">

#### `editor`

This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.

```
<template>
    <ckeditor :editor="editor" />
</template>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--tag-name">

#### `tag-name`

By default, the editor component creates a `<div>` container which is used as an element passed to the editor (for example, [ClassicEditor#element](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html#member-element)). The element can be configured, so for example to create a `<textarea>`, use the following directive:

```
<ckeditor :editor="editor" tag-name="textarea" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--v-model">

#### `v-model`

A [standard directive](https://v3.vuejs.org/guide/component-basics.html#using-v-model-on-components) for form inputs in Vue. Unlike [model-value](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--model-value), it creates a two–way data binding, which:

* Sets the initial editor content.
* Automatically updates the state of the application as the editor content changes (for example, as the user types).
* Can be used to set the editor content when necessary.

```
<template>
    <ckeditor :editor="editor" v-model="data" />
    <button @click="emptyEditor">Empty the editor</button>

    <h2>Editor data</h2>
    <code>{{ data }}</code>
</template>

<script setup>
import { ref } from 'vue';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

// Editor loading and configuration is skipped for brevity.

const data = ref( '<p>Hello world!</p>' );

function emptyEditor() {
    data.value = '';
}
</script>

```

In the above example, the `data` property will be updated automatically as the user types and the content changes. It can also be used to change (as in `emptyEditor()`) or set the initial content of the editor.

If you only want to execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--model-value">

#### `model-value`

Allows a one–way data binding that sets the content of the editor. Unlike [v-model](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--v-model), the value will not be updated when the content of the editor changes.

```
<template>
    <ckeditor :editor="editor" :model-value="data" />
</template>

<script setup>
import { ref } from 'vue';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

// Editor loading and configuration is skipped for brevity.

const data = ref( '<p>Hello world!</p>' );
</script>

```

To execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--config">

#### `config`

Specifies the [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor.

```
<template>
    <ckeditor :editor="editor" :config="config" />
</template>

<script setup>
import { computed } from 'vue';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

// Editor loading and configuration is skipped for brevity.

const config = computed( () => {
    const { Essentials, Paragraph, Bold, Italic } = cloud.data.value.CKEditor;
    const { FormatPainter } = cloud.data.value.CKEditorPremiumFeatures;

    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    };
} );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--disabled">

#### `disabled`

This directive controls the [isReadOnly](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property of the editor.

It sets the initial read–only state of the editor and changes it during its lifecycle.

```
<template>
    <ckeditor :editor="editor" :disabled="disabled" />
</template>

<script setup>
import { ref } from 'vue';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

// Editor loading and configuration is skipped for brevity.

const disabled = ref( true );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--disabletwowaydatabinding">

#### `disableTwoWayDataBinding`

Allows disabling the two-way data binding mechanism. The default value is `false`.

The reason for introducing this option is performance issues in large documents. After enabling this flag, the `v-model` directive will no longer update the connected value whenever the editor’s data is changed.

This option allows the integrator to disable the default behavior and only call the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method on demand, which prevents the slowdowns. You can read more in the [relevant issue](https://github.com/ckeditor/ckeditor5-vue/issues/246).

```
<template>
    <ckeditor :editor="editor" :disableTwoWayDataBinding="disableTwoWayDataBinding" />
</template>

<script setup>
import { ref } from 'vue';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

// Editor loading and configuration is skipped for brevity.

const disableTwoWayDataBinding = ref( true );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--component-events">

### Component events

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--ready">

#### `ready`

Corresponds to the [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) editor event.

```
<ckeditor :editor="editor" @ready="onEditorReady" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--focus">

#### `focus`

Corresponds to the [focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) editor event.

```
<ckeditor :editor="editor" @focus="onEditorFocus" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--blur">

#### `blur`

Corresponds to the [blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) editor event.

```
<ckeditor :editor="editor" @blur="onEditorBlur" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--input">

#### `input`

Corresponds to the [change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) editor event.

```
<ckeditor :editor="editor" @input="onEditorInput" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--destroy">

#### `destroy`

Corresponds to the [destroy](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-destroy) editor event.

**Note:** Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.

```
<ckeditor :editor="editor" @destroy="onEditorDestroy" />

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--using-the-document-editor-type">

#### Using the Document editor type

If you use the [Document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html) in your application, you need to [manually add the editor toolbar to the DOM](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create).

Since accessing the editor toolbar is not possible until after the editor instance is [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready), put your toolbar insertion code in a method executed upon the [ready](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--ready) event of the component, like in the following example:

```
<template>
    <ckeditor
        v-if="editor"
        v-model="data"
        :editor="editor"
        :config="config"
        @ready="onReady"
    />
</template>

<script setup>
import { ref, computed } from 'vue';
import { Ckeditor, useCKEditorCloud } from '@ckeditor/ckeditor5-vue';

const cloud = useCKEditorCloud( {
    version: '48.0.0'
} );

const data = ref( '<p>Hello world!</p>' );

const editor = computed( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    return cloud.data.value.CKEditor.ClassicEditor;
} );

const config = computed( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    const { Essentials, Paragraph, Bold, Italic, Mention } = cloud.data.value.CKEditor;
    const { SlashCommand } = cloud.data.value.CKEditorPremiumFeatures;

    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        plugins: [
            Essentials,
            Paragraph,
            Bold,
            Italic,
            Mention,
            SlashCommand
        ]
    };
} );

function onReady( editor ) {
    // Insert the toolbar before the editable area.
    editor.ui.getEditableElement().parentElement.insertBefore(
        editor.ui.view.toolbar.element,
        editor.ui.getEditableElement()
    );
}
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a **ready-to-use integration** featuring collaborative editing in a Vue application:

* [CKEditor 5 with real-time collaboration features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-vue)

It is not mandatory to build applications on top of the above sample, however, it should help you get started.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official Vue component. To translate the editor, pass the languages you need into the `translations` array inside the configuration of the `useCKEditorCloud` function.

```
<script setup>
import { useCKEditorCloud } from '@ckeditor/ckeditor5-vue';

const cloud = useCKEditorCloud( {
    version: '48.0.0',
    translations: [ 'es' ]
} );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--typescript-support">

#### TypeScript support

The CKEditor 5 Vue component is written in TypeScript and provides type definitions. If you use TypeScript in your project, you can take advantage of them. To do so, import the component and its types using an `import type` statement from a special package containing type definitions. Take a look at the following example:

```
<script setup>
import { useCKEditorCloud } from '@ckeditor/ckeditor5-vue';
import type { ClassicEditor } from 'https://cdn.ckeditor.com/typings/ckeditor5.d.ts';

const cloud = useCKEditorCloud( {
    version: '48.0.0',
    translations: [ 'es' ]
} );

const TestEditor = computed<typeof ClassicEditor | null>( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    const {
        ClassicEditor: BaseEditor,
        Paragraph,
        Essentials,
        Heading,
        Bold,
        Italic
    } = cloud.data.value.CKEditor;

    return class TestEditor extends BaseEditor {
        static builtinPlugins = [
            Essentials,
            Paragraph,
            Heading,
            Bold,
            Italic
        ];
    };
} );
</script>

```

In the example above, the ClassicEditor type is imported from the `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` package, while the editor itself loads from the CDN. Note that `https://cdn.ckeditor.com/typings/ckeditor5.d.ts` is not an actual URL to the CKEditor 5 types file but a synthetic TypeScript module providing type definitions for the editor. The `ckeditor5` package supplies the actual typings, which depend on the `@ckeditor/ckeditor5-react` package.

Although this setup might seem complex, it prevents users from directly importing anything from the `ckeditor5` package, which could lead to duplicated code issues.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--type-definitions-for-premium-features">

##### Type definitions for premium features

If you want to use types for premium features, you can import them similarly to the base editor types. Remember that you need to install the `ckeditor5-premium-features` package to use them. You can do it by running the following command:

```
npm install --save-dev ckeditor5-premium-features

```

After installing the package, you can import the types in the following way:

```
<script setup>
// ...
import type { Mention } from 'https://cdn.ckeditor.com/typings/ckeditor5-premium-features.d.ts';
// ...
</script>

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--known-issues">

### Known issues

While type definitions for the base editor should be available out of the box, some bundlers do not install the `ckeditor5` package, which provides typing for the editor. If you encounter any issues with the type definitions, you can install the `ckeditor5` package manually:

```
npm install --save-dev ckeditor5

```

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of this component is available on GitHub in <https://github.com/ckeditor/ckeditor5-vue>.

<a id="ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/css.html">source file: "ckeditor5/latest/getting-started/installation/css.html"</a>

## Compatibility with CSS frameworks

CKEditor 5 is compatible with most of the popular CSS frameworks. However, to properly integrate our robust HTML editor with some of them, additional tweaks may be necessary. This is mostly because:

* CSS frameworks often use a higher [CSS Specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) in their style sheets and override default editor styles, distorting the user interface.
* Modal components of various UI frameworks use high `z-index` values in their styles and render over (cover) the UI of CKEditor 5.
* Framework modals use an aggressive focus management policy that breaks the input fields in the rich-text editor (for example, the link input).

In this guide, you will learn how to address these integration issues and use the CKEditor 5 HTML editor with the most popular frontend frameworks.

<a id="ckeditor5/latest/getting-started/installation/css.html--compatibility-with-bootstrap">

### Compatibility with Bootstrap

<a id="ckeditor5/latest/getting-started/installation/css.html--bootstrap-modals">

#### Bootstrap modals

[Bootstrap](https://getbootstrap.com) modals cover the UI of the rich-text editor and break the input fields. Knowing that, you will need to take the following steps to get CKEditor 5 working in the Bootstrap environment:

* Configure the `z-index` of the floating editor UI (for example, balloons) to display it over the Bootstrap overlay.
* Configure Bootstrap so it stops “stealing” the focus from the rich-text editor input fields.

To address the first issue, add the following styles to your application:

```
/*
 * Configure the z-index of the editor UI, so when inside a Bootstrap
 * modal, it will be rendered over the modal.
 */
:root {
    --ck-z-default: 100;
    --ck-z-panel: calc( var(--ck-z-default) + 999 );
}

```

Pass the [focus: false](https://getbootstrap.com/docs/4.1/components/modal/#options) option to the Bootstrap `modal()` function to fix the second issue:

```
$( '#modal-container' ).modal( {
    focus: false
} );

```

[Check out the demo of CKEditor 5 rich-text editor working correctly with Bootstrap](https://codepen.io/ckeditor/pen/vzvgOe).

<a id="ckeditor5/latest/getting-started/installation/css.html--bootstrap-table-styles">

#### Bootstrap table styles

There is also a known [issue](https://github.com/ckeditor/ckeditor5/issues/3253) concerning table styles brought by Bootstrap breaking the table (widget) layout during editing. If you do not want any additional space around edited tables when using Bootstrap, add the following styles to your application:

```
/*
 * Override the width of the table set by Bootstrap content styles.
 * See: https://github.com/ckeditor/ckeditor5/issues/3253.
 */
.ck-content .table {
    width: auto;
}

```

<a id="ckeditor5/latest/getting-started/installation/css.html--compatibility-with-foundation">

### Compatibility with Foundation

CKEditor 5 requires some minor adjustments to the `z-index` of the UI to work properly with [Foundation](https://get.foundation/) (and with the [Reveal](https://revealjs.com/) modal, too).

```
/*
 * Configure the z-index of the editor UI, so when inside a Reveal modal,
 * it will be rendered over the modal.
 */
:root {
    --ck-z-default: 100;
    --ck-z-panel: calc( var(--ck-z-default) + 999 );
}

```

[Check out the demo of CKEditor 5 rich-text editor working correctly with Foundation](https://codepen.io/ckeditor/pen/VqXYQq).

<a id="ckeditor5/latest/getting-started/installation/css.html--compatibility-with-materialize">

### Compatibility with Materialize

If you want to use CKEditor 5 with [Materialize.css](https://materializecss.com/), you will need to take the following steps:

* Configure the base `z-index` of the floating editor UI so it is displayed over the Materialize modals.
* Bring back the default `.ck-input` class appearance (because Materialize overrides it with a higher specificity).
* Bring back the default `<ul>` and `<li>` appearance (because Materialize overrides it).
* Configure modals so they stop “stealing” the focus from the rich-text editor input fields.

Use the following CSS to address the issues with the `z-index` and selector specificity:

```
/*
 * Configure the z-index of the editor UI, so when inside a Materialize
 * modal, it will be rendered over the modal.
 */
:root {
    --ck-z-default: 100;
    --ck-z-panel: calc( var(--ck-z-default) + 999 );
}

/*
 * Bring back the default CKEditor&nbsp;5 input appearance by overriding
 * high–specificity styles brought by materialize.css.
 *
 * See: https://github.com/Dogfalo/materialize/blob/v1-dev/sass/components/forms/_input-fields.scss#L10-L40
 */
.ck input.ck-input.ck-input-text {
    box-shadow: var(--ck-inner-shadow),0 0;
    background: var(--ck-color-input-background);
    border: 1px solid var(--ck-color-input-border);
    padding: var(--ck-spacing-extra-tiny) var(--ck-spacing-medium);
    transition-property: box-shadow,border;
    transition: .2s ease-in-out;

    height: inherit;
    width: inherit;
    font-size: inherit;
    margin: 0;
    box-sizing: border-box;
}

.ck input.ck-input.ck-input-text:focus {
    border: var(--ck-focus-ring);
    box-shadow: var(--ck-focus-outer-shadow),var(--ck-inner-shadow);
}

```

```
/*
 * Bring back the default <ul> and <li> appearance.
 *
 * See: https://github.com/Dogfalo/materialize/blob/v1-dev/sass/components/_global.scss#L28-L37
 */
.ck.ck-content ul,
.ck.ck-content ul li {
  list-style-type: inherit;
}

.ck.ck-content ul {
  /* Default user agent style sheet. You can change it to your needs. */
  padding-left: 40px;
}

```

To change the behavior of the modals and prevent them from “stealing” the focus, use the [dismissible: false](https://materializecss.com/modals.html#options) option.

```
M.Modal.init( modal, { dismissible: false } );

// Or "jQuery way":
$( '#modal-container' ).modal( {
    dismissible: false
} );

```

[Check out the demo of CKEditor 5 rich-text editor working correctly with Materialize.css](https://codepen.io/ckeditor/pen/gZebwy).

<a id="ckeditor5/latest/getting-started/installation/css.html--compatibility-with-semantic-ui">

### Compatibility with Semantic-UI

CKEditor 5 works properly with [Semantic-UI](https://semantic-ui.com/). To use the balloon editor inside a modal, it is necessary to configure the `z-index` property of the floating editor UI to make it render over the modal:

```
/*
 * Configure the z-index of the editor UI, so when inside a Semantic-UI modal,
 * it will be rendered over the modal.
 */
:root {
    --ck-z-default: 100;
    --ck-z-panel: calc( var(--ck-z-default) + 999 );
}

```

<a id="ckeditor5/latest/getting-started/installation/css.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html">source file: "ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html"</a>

## CKEditor 5 real-time editing in Drupal

Drupal is a free and open-source web content management system (CMS) written in PHP. CKEditor 5 WYSIWYG rich text editor is the default editor module for Drupal. The [CKEditor 5 Premium Features module](https://www.drupal.org/project/ckeditor5%5Fpremium%5Ffeatures) provides instant integration of the real-time collaboration features with the editing platform.

Currently, the module includes a full set of [collaboration tools](#ckeditor5/latest/features/collaboration/collaboration.html), namely comments, track changes, and revision history. It also provides a set of essential formatting and navigation features as well as document import and export plugins.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--real-time-collaboration-in-drupal-with-ckeditor-5">

### Real-time collaboration in Drupal with CKEditor 5

With [real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) features, many users can work together to write, review, and discuss their content right within Drupal. No need to use different applications for drafting and commenting – you can do it all in one place.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--adding-comments">

#### Adding comments

The [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) feature allows users to discuss the content. It lets them add comments to any part of the content, including text and block elements such as embedded media or images. This is a great way of communication for many authors working on the same document.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--tracking-content-changes">

#### Tracking content changes

The [track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) feature shows change suggestions added by editors. These can be later accepted and added to the content or dismissed.

[Revision History](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) is a versioning tool that allows the making of document snapshots (revisions). You can name these snapshots and easily browse them to see what changes were made. You can also compare and restore previous versions of the content.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--notifications">

#### Notifications

There is also a dedicated, configurable notifications system developed especially for the CKEditor 5 Premium Features module for Drupal. It helps you stay up-to-date whenever someone mentions you in a document, comments, or replies to you, accepts or rejects suggestions, and so on. Integrate it with your custom plugin to get notifications via email, Slack, or other services.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--asynchronous-collaboration">

#### Asynchronous collaboration

You can use all the collaboration features **for [asynchronous editing](#ckeditor5/latest/features/collaboration/collaboration.html--asynchronous-collaboration)**. It is a collaboration mode when a single actor can work on the document at once, using the revision history, track changes, and comments features to interact with the previous and following editors, as the work happens sequentially.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--productivity-improving-features">

### Productivity-improving features

Apart from the real-time collaboration tools, the module provides various other plugins. The [format painter](#ckeditor5/latest/features/format-painter.html) feature lets users consistently style the edited text, while the [mentions](#ckeditor5/latest/features/mentions.html) feature allows you to tag other users in comments. Meanwhile, [slash commands](#ckeditor5/latest/features/slash-commands.html) let you create, insert, and format rich content on the go by typing the `/` character and choosing from many predefined actions, such as text formatting, and inserting headings, tables, or lists.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--fullscreen-mode">

#### Fullscreen mode

The fullscreen mode is a free-to-use plugin that maximizes the editing area. It is especially useful when using features like [document outline](#ckeditor5/latest/features/document-outline.html) or [comments](#ckeditor5/latest/features/collaboration/comments/comments.html) that take up extra space around the editor.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--document-converters">

#### Document converters

The module includes the [enhanced Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html) feature which makes pasting advanced rich-text content easy and reliable. Users can also use the [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) feature to import entire documents into the editor. Once the work is done or needs to be sent to another editor, handy one-click [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) and [export to Word](#ckeditor5/latest/features/converters/export-word.html) features offer portability and cross-platform interoperability.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--templates">

#### Templates

Easily defined document and content [templates](#ckeditor5/latest/features/template.html) make content creation faster and easier thanks to sets of predefined templates. These may define entire documents, like CVs, reports, or formal letters conforming to the company’s style guide. You can also use templates to create content blocks, such as pre-formatted tables, lists, and other block elements.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--ckeditor-5-plugin-pack">

### CKEditor 5 Plugin Pack

The [CKEditor 5 Plugin Pack](https://www.drupal.org/project/ckeditor5%5Fplugin%5Fpack) is a free-to-use module that offers multiple CKEditor 5 plugins that are not available in the Drupal core, extending editor’s functionality.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--features-available-in-the-ckeditor-5-plugin-pack-module">

#### Features available in the CKEditor 5 Plugin Pack module

* [Block indentation](#ckeditor5/latest/features/indent.html)
* [Find and replace](#ckeditor5/latest/features/find-and-replace.html)
* [Fonts family, size and colors](#ckeditor5/latest/features/font.html)
* [Highlight](#ckeditor5/latest/features/highlight.html)
* [Text transformation](#ckeditor5/latest/features/text-transformation.html)
* [To-do lists](#ckeditor5/latest/features/lists/todo-lists.html)
* [Word count](#ckeditor5/latest/features/word-count.html)
* Free version of [WProofreader](#ckeditor5/latest/features/spelling-and-grammar-checking.html) – limitation of the free version are listed [on this page](https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-documentation/ckeditor-5-plugin-pack/wproofreader-free-vs-premium-feature-comparison)

Plugin Pack also makes it possible to use some of the premium features for free.

Currently available premium features:

* [Templates](#ckeditor5/latest/features/template.html)
* Fullscreen mode

Detailed descriptions of each plugin can be found on the [CKEditor 5 Plugin Pack module page](https://www.drupal.org/project/ckeditor5%5Fplugin%5Fpack)

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--supported-drupal-versions">

### Supported Drupal versions

* Drupal 9 (requires [enabling CKEditor–5](https://www.drupal.org/docs/core-modules-and-themes/core-modules/experimental-ckeditor-5/installation-and-configuration-of-ckeditor-5-module-on-drupal-9))
* Drupal 10

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--requirements">

### Requirements

* PHP 8.0+
* Drupal 9.4 with CKEditor–5 enabled
* Drupal 10
* To-do list module requires Drupal 10.2+
* Templates module requires Drupal 10.3+

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--installation-and-configuration">

### Installation and configuration

Refer to the [Adding CKEditor–5 Premium Features module to Drupal 10](https://www.drupal.org/docs/contributed-modules/ckeditor-5-premium-features/how-to-install-and-set-up-the-module) guide in the Drupal documentation for details on how to install and set up the Premium Features module.

Refer to the [Adding CKEditor 5 Plugin Pack module to Drupal 10](https://www.drupal.org/docs/extending-drupal/contributed-modules/contributed-module-documentation/ckeditor-5-plugin-pack/how-to-install-and-set-up-the-module) guide in the Drupal documentation for details on how to install and set up the Plugin Pack module.

<a id="ckeditor5/latest/getting-started/installation/drupal-real-time-collaboration.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/angular.html"</a>

## Integrating CKEditor 5 with Angular from npm

Angular is a TypeScript-based, open-source, single-page web application framework. The CKEditor 5 component for Angular supports integrating different editor types.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--quick-start">

### Quick start

This guide assumes you already have an Angular project. To create such a project, you can use Angular CLI. Refer to the [Angular documentation](https://angular.io/cli) to learn more.

First, install the CKEditor 5 packages:

* `ckeditor5` – package with open-source plugins and features.
* `ckeditor5-premium-features` – package with premium plugins and features.

Depending on your configuration and chosen plugins, you may need to install the first or both packages.

```
npm install ckeditor5 ckeditor5-premium-features

```

Then, install the [CKEditor 5 WYSIWYG editor component for Angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular):

```
npm install @ckeditor/ckeditor5-angular

```

The following setup differs depending on the type of components you use.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--standalone-components">

#### Standalone components

Standalone components provide a simplified way to build Angular applications. They are enabled in Angular 17 by default. Standalone components aim to simplify the setup and reduce the need for `NGModules`. That is why you do not need such a module in this case.

Instead, add the `CKEditorModule` to the imports in your app component. The component needs the `standalone` option set to `true`. The example below shows how to use the component with open-source and premium plugins.

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    encapsulation: ViewEncapsulation.None,
    imports: [ CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';

    public Editor = ClassicEditor;
    public config = {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    }
}

```

Depending on the plugins used (open source only or premium too), you may need to import the first or both CSS files. Angular, by default, scopes styles to a particular component. Because of that, the editor may not detect attached styles. You must set the encapsulation option to `ViewEncapsulation.None` to turn this scoping off.

```
/* app.component.css */

@import 'ckeditor5/ckeditor5.css';
@import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

```

Then, use the `<ckeditor>` tag in the template to run the rich text editor:

```
<!-- app.component.html -->

<ckeditor [editor]="Editor" [config]="config" data="<p>Hello, world!</p>"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--ngmodule-components">

#### NGModule components

If you want to use NGModule components, add the `CKEditorModule` to the `imports` array. It will make the CKEditor 5 component available in your Angular application.

```
// app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';

import { AppComponent } from './app.component';

@NgModule( {
    declarations: [ AppComponent ],
    imports: [ BrowserModule, CKEditorModule ],
    providers: [],
    bootstrap: [ AppComponent ]
} )
export class AppModule { }

```

Then, import the editor into your Angular component and assign it to a `public` property to make it accessible from the template. The example below shows how to use the component with open-source and premium plugins.

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: [ './app.component.css' ],
    encapsulation: ViewEncapsulation.None
} )
export class AppComponent {
    title = 'angular';

    public Editor = ClassicEditor;
    public config = {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    }
}

```

Depending on the plugins you used, you may need to import the first or both CSS files. Angular, by default, scopes styles to a particular component. That’s why the editor may not detect attached styles. You must set the encapsulation option to `ViewEncapsulation.None` to turn this scoping off.

```
/* app.component.css */

@import 'ckeditor5/ckeditor5.css';
@import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

```

Finally, use the `<ckeditor>` tag in the template to run the rich text editor:

```
<!-- app.component.html -->

<ckeditor [editor]="Editor" [config]="config" data="<p>Hello, world!</p>"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--supported-input-properties">

### Supported `@Input` properties

The following `@Input` properties are supported by the CKEditor 5 rich text editor component for Angular:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--editor-required">

#### `editor` (required)

The [Editor](#ckeditor5/latest/getting-started/setup/editor-lifecycle.html) which provides the static [create()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) method to create an instance of the editor:

```
<ckeditor [editor]="Editor"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--config">

#### `config`

The [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor:

```
<ckeditor [config]="{ toolbar: [ 'heading', '|', 'bold', 'italic' ] }"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--data">

#### `data`

The initial data of the editor. It can be a static value:

```
<ckeditor data="<p>Hello, world!</p>"></ckeditor>

```

or a shared parent component’s property

```
@Component( {
    // ...
} )
export class MyComponent {
    public editorData = '<p>Hello, world!</p>';
    // ...
}

```

```
<ckeditor [data]="editorData"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--tagname">

#### `tagName`

The tag name of the HTML element on which the rich text editor will be created.

The default tag is `<div>`.

```
<ckeditor tagName="textarea"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--disabled">

#### `disabled`

Controls the editor’s [read–only](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) state:

```
@Component( {
    // ...
} )
export class MyComponent {
    public isDisabled = false;
    // ...
    toggleDisabled() {
        this.isDisabled = !this.isDisabled
    }
}

```

```
<ckeditor [disabled]="isDisabled"></ckeditor>

<button (click)="toggleDisabled()">
    {{ isDisabled ? 'Enable editor' : 'Disable editor' }}
</button>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--watchdog">

#### `watchdog`

An instance of the [ContextWatchdog](../../../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html) class that is responsible for providing the same context to multiple editor instances and restarting the whole structure in case of crashes.

```
import { Editor, Context, ContextWatchdog } from 'ckeditor5';

@Component( {
    // ...
} )
export class MyComponent {
    public editor = Editor;
    public watchdog: any;
    public ready = false;

    ngOnInit() {
        const contextConfig = {};

        this.watchdog = new ContextWatchdog( Context );

        this.watchdog.create( contextConfig )
            .then( () => {
                this.ready = true;
            } );
    }
}

```

```
<div *ngIf="ready">
    <ckeditor [watchdog]="watchdog"></ckeditor>
    <ckeditor [watchdog]="watchdog"></ckeditor>
    <ckeditor [watchdog]="watchdog"></ckeditor>
</div>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--editorwatchdogconfig">

#### `editorWatchdogConfig`

If the `watchdog` property is not used, [EditorWatchdog](../../../api/module%5Fwatchdog%5Feditorwatchdog-EditorWatchdog.html) will be used by default. `editorWatchdogConfig` property allows for passing a [config](../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) to that watchdog.

```
@Component( {
    // ...
} )
export class MyComponent {
    public myWatchdogConfig = {
        crashNumberLimit: 5,
        // ...
    };
    // ...
}

```

```
<ckeditor [editorWatchdogConfig]="myWatchdogConfig"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--disabletwowaydatabinding">

#### `disableTwoWayDataBinding`

Allows disabling the two-way data binding mechanism. The default value is `false`.

We introduced this option to address performance issues in large documents. By default, while using the `ngModel` directive, whenever the editor’s data is changed, the component must synchronize the data between the editor instance and the connected property. This results in calling the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) function, which causes a massive slowdown while typing in large documents.

This option allows the integrator to disable the default behavior and only call the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method on demand, which prevents the slowdowns. You can read more in the [relevant issue](https://github.com/ckeditor/ckeditor5-angular/issues/141).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--supported-output-properties">

### Supported `@Output` properties

The following `@Output` properties are supported by the CKEditor 5 rich text editor component for Angular:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--ready">

#### `ready`

Fired when the editor is ready. It corresponds with the [editor#ready](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) event.  
It is fired with the editor instance.

Note that this method might be called multiple times. Apart from initialization, it is also called whenever the editor is restarted after a crash. Do not keep the reference to the editor instance internally, because it will change in case of a restart. Instead, you should use the `watchdog.editor` property.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--change">

#### `change`

Fired when the content of the editor has changed. It corresponds with the [editor.model.document#change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.  
It is fired with an object containing the editor and the CKEditor 5 `change:data` event object.

```
<ckeditor [editor]="Editor" (change)="onChange($event)"></ckeditor>

```

```
import { ClassicEditor } from 'ckeditor5';
import { ChangeEvent } from '@ckeditor/ckeditor5-angular/ckeditor.component';

@Component( {
    // ...
} )
export class MyComponent {
    public Editor = ClassicEditor;

    public onChange( { editor }: ChangeEvent ) {
        const data = editor.getData();

        console.log( data );
    }
    // ...
}

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--blur">

#### `blur`

Fired when the editing view of the editor is blurred. It corresponds with the [editor.editing.view.document#blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.  
It is fired with an object containing the editor and the CKEditor 5 `blur` event data.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--focus">

#### `focus`

Fired when the editing view of the editor is focused. It corresponds with the [editor.editing.view.document#focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.  
It is fired with an object containing the editor and the CKEditor 5 `focus` event data.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--error">

#### `error`

Fired when the editor crashes. Once the editor has crashed, the internal watchdog mechanism restarts the editor and fires the [ready](#ckeditor5/latest/getting-started/installation/self-hosted/angular.html--ready) event.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--integration-with-ngmodel">

### Integration with `ngModel`

The component implements the [ControlValueAccessor](https://angular.io/api/forms/ControlValueAccessor) interface and works with the `ngModel`. Here is how to use it:

Create some model in your component to share with the editor:

```
@Component( {
    // ...
} )
export class MyComponent {
    public model = {
        editorData: '<p>Hello, world!</p>'
    };
    // ...
}

```

Use the model in the template to enable a two–way data binding:

```
<ckeditor [(ngModel)]="model.editorData" [editor]="Editor"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--styling">

#### Styling

The CKEditor 5 rich text editor component for Angular can be styled using the component style sheet or using a global style sheet. See how to set the CKEditor 5 component’s height using these two approaches.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--setting-the-height-via-the-component-style-sheet">

#### Setting the height via the component style sheet

First, create a (S)CSS file in the parent component’s directory and style the given editor’s part preceded by the `:host` and `::ng-deep` pseudo selectors:

```
/* src/app/app.component.css */

:host ::ng-deep .ck-editor__editable_inline {
    min-height: 500px;
}

```

Then, in the parent component, add the relative path to the above style sheet:

```
/* src/app/app.component.ts */

@Component( {
    // ...
    styleUrls: [ './app.component.css' ]
} )

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--setting-the-height-via-a-global-style-sheet">

##### Setting the height via a global style sheet

To style the component using a global style sheet, first, create it:

```
/* src/styles.css */

.ck-editor__editable_inline {
    min-height: 500px;
}

```

Then, add it to the `angular.json` configuration file:

```
"architect": {
    "build": {
        "options": {
            "styles": [
                { "input": "src/styles.css" }
            ]
        }
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--setting-the-placeholder">

##### Setting the placeholder

To display the [placeholder](#ckeditor5/latest/features/editor-placeholder.html) in the main editable element, set the `root.placeholder` field in the CKEditor 5 rich text editor component configuration:

```
@Component( {
    // ...
} )
export class MyComponent {
    public config = {
        root: {
            placeholder: 'Type the content here!'
        }
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--accessing-the-editor-instance">

#### Accessing the editor instance

The CKEditor 5 rich text editor component provides all the functionality needed for most use cases. When access to the full CKEditor 5 API is needed you can get the editor instance with an additional step.

To do this, create a template reference variable `#editor` pointing to the `<ckeditor>` component:

```
<ckeditor #editor [editor]="Editor"></ckeditor>

```

Then get the `<ckeditor>` component using a property decorated by `@ViewChild( 'editor' )` and access the editor instance when needed:

```
@Component()
export class MyComponent {
    @ViewChild( 'editor' ) editorComponent: CKEditorComponent;

    public getEditor() {
        // Warning: This may return "undefined" if the editor is hidden behind the `*ngIf` directive or
        // if the editor is not fully initialised yet.
        return this.editorComponent.editorInstance;
    }
}

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--using-the-document-editor-type">

#### Using the Document editor type

If you want to use the [document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html), you need to [add the toolbar to the DOM manually](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create):

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { DecoupledEditor, Essentials, Italic, Paragraph, Bold } from 'ckeditor5';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: [ './app.component.css' ],
    encapsulation: ViewEncapsulation.None
    imports: [ CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';

    public Editor = DecoupledEditor;
    public config = {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Bold, Essentials, Italic, Paragraph ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
    }
    public onReady( editor: DecoupledEditor ): void {
        const element = editor.ui.getEditableElement()!;
        const parent = element.parentElement!;

        parent.insertBefore(
            editor.ui.view.toolbar.element!,
            element
        );
    }
}

```

Import the needed CSS style sheet:

```
/* app.component.css */

@import 'ckeditor5/ckeditor5.css';

```

And then, link the method in the template:

```
<!-- app.component.html -->

<ckeditor [editor]="Editor" data="<p>Hello, world!</p>" (ready)="onReady($event)"></ckeditor>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a few **ready-to-use integrations** featuring collaborative editing in Angular applications:

* [CKEditor 5 with real-time collaboration features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-angular)
* [CKEditor 5 with real-time collaboration and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-revision-history-for-angular)
* [CKEditor 5 with the revision history feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/revision-history-for-angular)
* [CKEditor 5 with the track changes feature](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/track-changes-for-angular)

It is not mandatory to build applications on top of the above samples, however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--localization">

#### Localization

CKEditor 5 supports multiple UI languages, and so does the official Angular component. Follow the instructions below to translate CKEditor 5 in your Angular application.

Similarly to CSS style sheets, both packages have separate translations. Import them as shown in the example below. Then, pass them to the `translations` array of the `config` property.

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor } from 'ckeditor5';
// More imports...

import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: [ './app.component.css' ],
    encapsulation: ViewEncapsulation.None
    imports: [ CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';
    public Editor = ClassicEditor;
    public config = {
        // ... Other configuration options ...
        translations: [ coreTranslations, premiumFeaturesTranslations ]
    }
}

```

For advanced usage see the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--known-issues">

### Known issues

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--module-resolution">

#### Module resolution

The `moduleResolution` option of the TypeScript configuration determines the algorithm for finding and resolving modules from `node_modules`. In Angular 17, the option is set to `node` by default. This option prevents type declaration for editor translations from being correctly loaded. To fix it, you have several options:

* You can set the `moduleResolution` option to `bundler`. It is the recommended setting in TypeScript 5.0+ for applications that use a bundler. And it is a recommended way of fixing this problem. You can check other solutions below for lower TypeScript versions.
* You can tell the TypeScript compiler to suppress the problem using the `// @ts-expect-error` comment above the imported translations.
* You can update Angular to version 18, where the `moduleResolution` option is set to `bundler` by default.
* You can import translations directly from our CDN, like: `import ‘https://cdn.ckeditor.com/ckeditor5/48.0.0/translations/es.umd.js’;`. This way, the editor will load the translations automatically, so you do not need to pass them manually into the configuration.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--jest-testing">

#### Jest testing

You can use Jest as a test runner in Angular apps. Unfortunately, Jest does not use a real browser. Instead, it runs tests in Node.js that uses JSDOM. JSDOM is not a complete DOM implementation, and while it is sufficient for standard apps, it cannot polyfill all the DOM APIs that CKEditor 5 requires.

For testing CKEditor 5, it is recommended to use testing frameworks that utilize a real browser and provide a complete DOM implementation. Some popular options include:

* [Vitest](https://vitest.dev/)
* [Playwright](https://playwright.dev/)
* [Cypress](https://www.cypress.io/)

These frameworks offer better support for testing CKEditor 5 and provide a more accurate representation of how the editor behaves in a real browser environment.

If this is not possible and you still want to use Jest, you can mock some of the required APIs. Below is an example of how to mock some of the APIs used by CKEditor 5:

```
import { TextEncoder } from 'util';

beforeAll( () => {
    window.TextEncoder = TextEncoder;

    window.scrollTo = jest.fn();

    window.ResizeObserver = class ResizeObserver {
        observe() {}
        unobserve() {}
        disconnect() {}
    };

    for ( const key of [ 'InputEvent', 'KeyboardEvent' ] ) {
        window[ key ].prototype.getTargetRanges = () => {
            const range = new StaticRange( {
                startContainer: document.body.querySelector( '.ck-editor__editable p' ),
                startOffset: 0,
                endContainer: document.body.querySelector( '.ck-editor__editable p' ),
                endOffset: 0
            } );

            return [ range ];
        };
    }

    const getClientRects = () => ({
        item: () => null,
        length: 0,
        [Symbol.iterator]: function* () {}
    });

    Range.prototype.getClientRects = getClientRects;
    Element.prototype.getClientRects = getClientRects;

    if ( !Document.prototype.createElementNS ) {
        Document.prototype.createElementNS = ( namespace, name ) => {
            const element = document.createElement( name );
            element.namespaceURI = namespace;
            return element;
        };
    }
} );

```

These mocks should be placed before the tests that use CKEditor 5\. They are imperfect and may not cover all the cases, but they should be sufficient for basic initialization and rendering the editor. Keep in mind that they are not a replacement for proper browser testing.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--supported-angular-versions">

### Supported Angular versions

Because of the breaking changes in the Angular library output format, the `@ckeditor/ckeditor5-angular` package is released in the following versions to support various Angular ecosystems:

| CKEditor 5 Angular component version | Angular version | Details                                                                                                                                                                                                      |
| ------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Actively supported versions          |                 |                                                                                                                                                                                                              |
| ^11                                  | 19+             | Requires CKEditor 5 in version [47](https://github.com/ckeditor/ckeditor5/releases/tag/v47.0.0) or higher.                                                                                                   |
| Past releases (no longer maintained) |                 |                                                                                                                                                                                                              |
| ^10                                  | 16+             | Requires CKEditor 5 in version [46](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.0) or higher.                                                                                                   |
| ^9                                   | 16+             | Migration to TypeScript 5\. Declaration files are not backward compatible. Requires CKEditor 5 in version [43](https://github.com/ckeditor/ckeditor5/releases/tag/v43.0.0) or higher.                        |
| ^8                                   | 13+             | Requires CKEditor 5 in version [42](https://github.com/ckeditor/ckeditor5/releases/tag/v42.0.0) or higher.                                                                                                   |
| ^7                                   | 13+             | Changes in peer dependencies ([issue](https://github.com/ckeditor/ckeditor5-angular/issues/376)). Requires CKEditor 5 in version [37](https://github.com/ckeditor/ckeditor5/releases/tag/v37.0.0) or higher. |
| ^6                                   | 13+             | Requires CKEditor 5 in version [37](https://github.com/ckeditor/ckeditor5/releases/tag/v37.0.0) or higher.                                                                                                   |
| ^5                                   | 13+             | Requires Angular in version 13+ or higher.                                                                                                                                                                   |
| ^4                                   | 9.1+            | Requires CKEditor 5 in version [34](https://github.com/ckeditor/ckeditor5/releases/tag/v34.0.0) or higher.                                                                                                   |
| ^3                                   | 9.1+            | Requires Node.js in version 14 or higher.                                                                                                                                                                    |
| ^2                                   | 9.1+            | Migration to TypeScript 4\. Declaration files are not backward compatible.                                                                                                                                   |
| ^1                                   | 5.x - 8.x       | Angular versions no longer maintained.                                                                                                                                                                       |

All available Angular versions are [listed on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular), where they can be pulled from.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of the CKEditor 5 rich text editor component for Angular is available on GitHub at <https://github.com/ckeditor/ckeditor5-angular>.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/angular.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/dotnet.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/dotnet.html"</a>

## Integrating CKEditor 5 with .NET from ZIP

As a pure JavaScript/TypeScript application, the CKEditor 5 HTML editor will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 in a non-JS framework of your choice, for example, Microsoft’s [.NET](https://dotnet.microsoft.com/).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/dotnet.html--setting-up-the-project">

### Setting up the project

For the purpose of this guide, we will use a basic ASP.NET Core project created with `dotnet new webapp`. You can refer to the [ASP.NET Core documentation](https://learn.microsoft.com/en-us/aspnet/core/getting-started/?view=aspnetcore-7.0) to learn how to set up a project in the framework.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/dotnet.html--integrating-using-zip">

### Integrating using ZIP

After downloading and unpacking the ZIP archive, copy the `ckeditor5.js` and `ckeditor5.css` files in the `wwwroot/lib/ckeditor5/` directory. The folder structure of your app should resemble this one.

```
├── bin
├── obj
├── Pages
│   ├── Index.cshtml
│   └── ...
├── Properties
├── wwwroot
│   ├── css
│   ├── js
│   ├── lib
|      ├── bootstrap
|      ├── ckeditor5
|          ├── ckeditor5.js
|          └── ckeditor5.css
|      ├── jquery
|      ├── jquery-validation
|      ├── jquery-validation-unobtrusive
│   └── favicon.ico
├── appsettings.Development.json
├── appsettings.json
└── ...

```

Once you have all the dependencies of CKEditor 5, modify the `Index.cshtml` file in the `Pages` directory to import them. All the necessary markup is in the `index.html` file from the ZIP archive. You can copy and paste it into the `<script>` tag of your page. Pay attention to the paths of the import map and CSS link – they should reflect your folder structure. The template should look similar to the one below:

```
@page
@using Microsoft.AspNetCore.Components
@{
    ViewData["Title"] = "Home Page";
    var data = new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "ckeditor5", "/lib/ckeditor5/ckeditor5.js" },
        { "ckeditor5/", "/lib/ckeditor5/" },
    }, null, null);
}
<link href="~/lib/ckeditor5/ckeditor5.css" rel="stylesheet" />
<div class="main-container">
    <div id="editor">
        <p>Hello from CKEditor 5!</p>
    </div>
</div>
<script type="importmap" asp-importmap="@data"></script>
<script type="module">
    import {
        ClassicEditor,
        Essentials,
        Paragraph,
        Bold,
        Italic,
        Font
    } from 'ckeditor5';

    ClassicEditor
        .create( {
            attachTo: document.querySelector( '#editor' ),
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Paragraph, Bold, Italic, Font ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
            ]
        } )
        .then( editor => {
            window.editor = editor;
        } )
        .catch( error => {
            console.error( error );
        } );
</script>

```

Finally, in the root directory of your .NET project, run `dotnet watch run` to see the app in action.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/dotnet.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/electron.html"</a>

## Integrating CKEditor 5 with Electron from ZIP

[Electron](https://www.electronjs.org/) is an open-source framework that allows developers to create cross-platform desktop applications using web technologies such as HTML, CSS, and JavaScript. It combines the Node.js runtime and the Chromium rendering engine, enabling a single codebase to be used for cross-platform apps that work on Windows, macOS, and Linux.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--quick-start">

### Quick start

This guide will show you how to integrate CKEditor 5 with an Electron application using the ZIP archive. If you are new to Electron, check out their [official tutorial](https://www.electronjs.org/docs/latest/tutorial/tutorial-prerequisites).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--setting-up-an-electron-project">

#### Setting up an Electron project

The quickest way to set up an Electron project is to use Electron Forge’s `create-electron-app` command. [Follow the Getting Started guide](https://www.electronforge.io/) to create the application.

When executing `npx create-electron-app@latest my-app` in the terminal, you will be prompted to choose a bundler and a language. For the sake of this tutorial, we have chosen to use Vite and vanilla JavaScript.

When the setup is finished, you should be able to go to the app’s directory and run it by executing:

```
cd my-app
npm start

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--integrating-ckeditor-5-with-electron-using-the-zip-archive">

### Integrating CKEditor 5 with Electron using the ZIP archive

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--preparing-the-zip-package-with-ckeditor-5">

#### Preparing the ZIP package with CKEditor 5

Now it is time to prepare a ZIP package with CKEditor 5 that will be used inside your Electron app. CKEditor 5 offers an Online Builder that allows you to configure your editor easily through a user-friendly interface. The Online Builder provides a convenient way to select features, plugins, and customize the toolbar according to your specific requirements without writing any code.

To create your custom CKEditor 5 build, visit the [CKEditor 5 Online Builder](https://ckeditor.com/ckeditor-5/builder/). After choosing all desired features and settings for your editor, you will reach the final step where you can choose the preferred technology and integration method. For Electron integration, select “Vanilla JavaScript” and “Self-hosted (ZIP)”. In the last step, download the ZIP archive containing the editor.

The downloaded ZIP archive includes all files necessary for integrating CKEditor 5 into your Electron app, including the main JavaScript file, stylesheets, and sample implementation code. This package is ready for integration and does not require any additional build steps. Once you have your custom CKEditor 5 package, you can add it to your main Electron app folder.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--project-structure">

#### Project structure

After following all the steps described so far, your app’s structure should resemble this one:

```
├── ckeditor5-builder
├── forge.config.js
├── index.html
├── node_modules/
├── package-lock.json
├── package.json
├── src/
│   ├── index.css
│   ├── main.js
│   ├── preload.js
│   └── renderer.js
├── vite.main.config.mjs
├── vite.preload.config.mjs
└── vite.renderer.config.mjs

```

With `ckeditor5-builder` being the unzipped folder downloaded from the [Online Builder](https://ckeditor.com/ckeditor-5/builder/).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--implementing-the-editor">

#### Implementing the editor

Inside the `src/` folder, create a new file `editor.js` with the following content:

```
const {
    ClassicEditor,
    Essentials,
    Bold,
    Italic,
    Font,
    Paragraph
} = CKEDITOR;

const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
            'formatPainter'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

This code imports all necessary CKEditor 5 plugins and initializes the editor instance with the provided configuration.

Now modify the `index.html` file so it looks like this:

```
<!doctype html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Hello World!</title>

        <link rel="stylesheet" href="./ckeditor5-builder/ckeditor5/ckeditor5.css">
        <link rel="stylesheet" href="./ckeditor5-builder/ckeditor5-premium-features/ckeditor5-premium-features.css">
    </head>
    <body>
        <h1>Hello Electron and CKEditor 5!</h1>
        <p>Welcome to your Electron application. Below you should see a working instance of CKEditor 5:</p>

        <div id="editor"></div>

        <script src="./ckeditor5-builder/ckeditor5/ckeditor5.umd.js"></script>
        <script src="./ckeditor5-builder/ckeditor5-premium-features/ckeditor5-premium-features.umd.js"></script>
        <script src="./src/editor.js"></script>

        <script type="module" src="/src/renderer.js"></script>
    </body>
</html>

```

Here we adjusted the structure to include the `<div>` placeholder for the editor instance. We have also loaded the editor’s styles, browser build files, and finally the `editor.js` file, which is responsible for tying everything together and initializing the editor.

You can now execute `npm start` to run the Electron app. It should automatically open a window with an editor instance ready to be used:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--obtaining-a-premium-features-license-key">

### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/electron.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/jquery.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/jquery.html"</a>

## Integrating CKEditor 5 with jQuery using npm

This guide will walk you through the process of integrating CKEditor 5 with jQuery using npm packages. jQuery is a fast, small, and feature-rich JavaScript library that simplifies HTML document traversal and manipulation, event handling, and animation. By combining it with CKEditor 5 using npm packages, you can leverage jQuery’s powerful DOM manipulation capabilities while enjoying the rich editing experience that CKEditor 5 provides.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/jquery.html--installing-ckeditor-5-using-npm">

### Installing CKEditor 5 using npm

To begin integrating CKEditor 5 with jQuery, you first need to install the required packages using npm. This approach provides access to all the necessary files including the editor engine, plugins, and style sheets that you can import directly into your application.

Install CKEditor 5 using npm by running the following command in your project directory:

```
npm install ckeditor5

```

You also need to install jQuery if you have not done so already:

```
npm install jquery

```

Once the packages are installed, you can import the necessary modules and style sheets directly into your JavaScript code. Create a JavaScript file for your application logic, then import CKEditor 5 and jQuery.

Here is the complete integration code combining jQuery and CKEditor 5:

```
import $ from 'jquery';

import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

$( document ).ready( () => {
    ClassicEditor
        .create( {
            attachTo: $( '#editor' )[ 0 ],
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
            ]
        } )
        .then( editor => {
            // Editor initialized successfully.
            console.log( 'CKEditor&nbsp;5 initialized with jQuery!' );
        } )
        .catch( error => {
            console.error( 'Error initializing CKEditor&nbsp;5:', error );
        } );
} );

```

Pass the imported plugins inside the configuration to the `create()` method and add toolbar items where applicable.

The first argument in the `create()` function is a DOM element for the editor placement, so you need to add it to your HTML page.

```
<div id="editor">
    <p>Hello from CKEditor&nbsp;5 with jQuery!</p>
</div>

```

That is all the code you need to see a bare-bone editor running in your web browser.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/jquery.html--installing-ckeditor-5-premium-features-using-npm">

### Installing CKEditor 5 Premium Features using npm

To extend your CKEditor 5 and jQuery integration with premium features, you need to install the premium features package separately.

Install the CKEditor 5 Premium Features package using npm by running the following command in your project directory:

```
npm install ckeditor5-premium-features

```

Now, you can import all the modules from both the `ckeditor5` and `ckeditor5-premium-features` packages. Additionally, you have to import CSS styles separately.

```
import $ from 'jquery';

import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

$( document ).ready( () => {
    ClassicEditor
        .create( {
            attachTo: $( '#editor' )[ 0 ],
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ]
        } )
        .then( editor => {
            // Editor initialized successfully with premium features.
            console.log( 'CKEditor&nbsp;5 with premium features initialized using jQuery!' );
        } )
        .catch( error => {
            console.error( 'Error initializing CKEditor&nbsp;5 with premium features:', error );
        } );
} );

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/jquery.html--obtaining-a-premium-features-license-key">

#### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/jquery.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/laravel.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/laravel.html"</a>

## Integrating CKEditor 5 with Laravel from ZIP

As a pure JavaScript/TypeScript application, the CKEditor 5 HTML editor will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 in a non-JS framework of your choice, for example, the PHP-based [Laravel](https://laravel.com/).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/laravel.html--setting-up-the-project">

### Setting up the project

This guide assume you have a Laravel project. You can create a basic Laravel project using [Composer](https://getcomposer.org/). Refer to the [Laravel documentation](https://laravel.com/docs/10.x/installation) to learn how to set up a project in the framework.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/laravel.html--integrating-using-zip">

### Integrating using ZIP

After downloading and unpacking the ZIP archive, copy the `ckeditor5.js` and `ckeditor5.css` files in the `public/assets/vendor/` directory. The folder structure of your app should resemble this one.

```
├── app
├── bootstrap
├── config
├── database
├── public
│   ├── assets
|      ├── vendor
|          ├── ckeditor5.js
|          └── ckeditor5.css
│   ├── .htaccess
│   ├── favicon.ico
│   ├── index.php
│   └── robots.txt
├── resources
│   ├── views
|      ├── welcome.blade.php
|      └── ...
├── routes
└── ...

```

Having all the dependencies of CKEditor 5, modify the `welcome.blade.php` file in the `resources/views` directory to import them. All the necessary markup is in the `index.html` file from the ZIP archive. You can copy and paste it into your template. Pay attention to the paths of the import map and CSS link – they should reflect your folder structure. The template should look similar to the one below:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>CKEditor 5 - Quick start ZIP</title>
        <link rel="stylesheet" href="../../assets/vendor/ckeditor5.css">
        <style>
            .main-container {
                width: 795px;
                margin-left: auto;
                margin-right: auto;
            }
        </style>
    </head>
    <body>
        <div class="main-container">
            <div id="editor">
                <p>Hello from CKEditor 5!</p>
            </div>
        </div>
        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "../../assets/vendor/ckeditor5.js",
                    "ckeditor5/": "../../assets/vendor/"
                }
            }
        </script>
        <script type="module">
            import {
                ClassicEditor,
                Essentials,
                Paragraph,
                Bold,
                Italic,
                Font
            } from 'ckeditor5';

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    plugins: [ Essentials, Paragraph, Bold, Italic, Font ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ]
                } )
                .then( editor => {
                    window.editor = editor;
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

Finally, in the root directory of your Laravel project, run `php artisan serve` to see the app in action.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/laravel.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/next-js.html"</a>

## Integrating CKEditor 5 with Next.js from npm

[Next.js](https://nextjs.org/) is a React meta-framework that helps create full-stack web applications. It offers different rendering strategies like server-side rendering (SSR), client-side rendering (CSR), or static site generation (SSG). Additionally, it provides file-based routing, automatic code splitting, and other handy features out of the box.

Next.js 13 introduced a new App Router as an alternative to the previous Pages Router. App Router supports server components and is more server-centric than Pages Router, which is client-side oriented.

CKEditor 5 does not support server-side rendering, but you can integrate it with the Next.js framework. In this guide, you will add the editor to a Next.js project using both routing paradigms. For this purpose, you will need [Next.js CLI](https://nextjs.org/docs/app/api-reference/create-next-app), and the official [CKEditor 5 React component](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Next project. To create such a project, you can use CLI like `create-next-app`. Refer to the [Next.js documentation](https://nextjs.org/docs/app/api-reference/create-next-app) to learn more.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html--installing-from-npm">

### Installing from npm

First, install the CKEditor 5 packages:

* `ckeditor5` – package with open-source plugins and features.
* `ckeditor5-premium-features` – package with premium plugins and features.

Depending on your configuration and chosen plugins, you may need to install the first or both packages.

```
npm install ckeditor5 ckeditor5-premium-features

```

Next.js is based on React, so install the [CKEditor 5 WYSIWYG editor component for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react), too:

```
npm install @ckeditor/ckeditor5-react

```

Next, you will use the installed dependencies in a React component. Create a new component in the components directory, for example, `components/custom-editor.js`. Inside the component file, import all necessary dependencies. Then, create a functional component that returns the CKEditor 5 React component. The below example shows how to use the component with open-source and premium plugins.

App Router, by default, uses server components. It means you need to mark a component as client-side explicitly. You can achieve that by using the `'use client'` directive at the top of a file, above your imports. You do not need the directive if you use the Pages Router.

```
// components/custom-editor.js
'use client' // Required only in App Router.

import { CKEditor } from '@ckeditor/ckeditor5-react';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

function CustomEditor() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ],
                root: {
                    initialData: '<p>Hello from CKEditor 5 in Next.js!</p>'
                }
            } }
        />
    );
}

export default CustomEditor;

```

The `CustomEditor` component is ready to be used inside a page. The page’s directory will differ depending on the chosen routing strategy.

The CKEditor 5 HTML editor is a client-side text editor and relies on the browser APIs, so you need to disable server-side rendering for our custom component. You can lazily load the component using the `dynamic()` function built into Next.js.

Prepare a wrapper for the `CustomEditor` component to load it on the client side.

```
// components/client-side-custom-editor.js
'use client' // Required only in App Router.

import dynamic from 'next/dynamic';

const ClientSideCustomEditor = dynamic( () => import( '@/components/custom-editor' ), { ssr: false } );

export default ClientSideCustomEditor;

```

And then use it in your application.

```
// app/page.js (App Router)
// pages/index.js (Pages Router)

import ClientSideCustomEditor from '@/components/client-side-custom-editor';

function Home() {
  return (
    <ClientSideCustomEditor />
  );
}

export default Home;

```

You can run your project now. If you chose `create-next-app`, type `npm run dev` to see your application in the browser.

Also, pay attention to the import path – this guide uses the [default import alias](https://nextjs.org/docs/app/building-your-application/configuring/absolute-imports-and-module-aliases) (@). If you did not configure it, change the path appropriately.

In the example above, we only used basic features of the `<CKEditor>` component. To learn more about additional features and configuration options, refer to the [React integration guide](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide several **ready-to-use integrations** featuring collaborative editing in Next.js applications:

* [CKEditor 5 with real-time collaboration features and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-next)
* [CKEditor 5 with offline comments, track changes and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/collaboration-for-next)

It is not mandatory to build applications on top of the above samples, however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/next-js.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html"</a>

## Integrating CKEditor 5 with Nuxt from npm

[Nuxt](https://nuxt.com/) is a Vue.js meta-framework for creating full-stack web applications. It offers everything you would expect from a modern framework, including various rendering modes, file-based routing, automatic code splitting, a large ecosystem of plugins and hosting integrations, and more.

The CKEditor 5 HTML editor does not support server-side rendering, but you can integrate it with the Nuxt framework. In this guide, you will add the editor to a Nuxt project. For this purpose, you will need a [Nuxt project](https://nuxt.com/docs/getting-started/installation) and the official [CKEditor 5 Vue component](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Nuxt project. To create such a project, follow the [Nuxt installation guide](https://nuxt.com/docs/getting-started/installation).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html--installing-from-npm">

### Installing from npm

First, install the CKEditor 5 packages:

* `ckeditor5` – package with open-source plugins and features.
* `ckeditor5-premium-features` – package with premium plugins and features.

Depending on your configuration and chosen plugins, you may need to install the first or both packages.

```
npm install ckeditor5 ckeditor5-premium-features

```

Nuxt is based on Vue.js, so install the [CKEditor 5 WYSIWYG editor component for Vue.js](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue), too:

```
npm install @ckeditor/ckeditor5-vue

```

Next, you will use the installed dependencies in a Vue.js component. Create a new component in the `components` directory, for example, `components/Editor.vue`. It will use the `<ckeditor>` component to run the editor. The following example shows a single file component with open-source and premium CKEditor 5 plugins.

```
<template>
    <ckeditor
        v-model="data"
        :editor="ClassicEditor"
        :config="config"
    />
</template>

<script setup>
import { ref, computed } from 'vue';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

const data = ref( '<p>Hello world!</p>' );

const config = computed( () => {
    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    };
} );
</script>

```

Now, you can import and use the `Editor.vue` component anywhere in your application.

```
<template>
    <ClientOnly>
        <Editor />
    </ClientOnly>
</template>

```

Notice that the `<Editor>` component is wrapped in a `<ClientOnly>` component. It is required because CKEditor 5 does not support server-side rendering. The `<ClientOnly>` component ensures that the editor is rendered only on the client side.

You can run your project now using the `npm run dev` command to see your application in the browser.

In the example above, we only used basic features of the `<ckeditor>` component. To learn more about additional features and configuration options, refer to the [Vue.js integration guide](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/nuxt.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html"</a>

## Installing Vanilla JS CKEditor 5 from npm or ZIP

CKEditor 5 is a powerful, rich text editor you can embed in your web application. This guide will show you the fastest way to use it with npm or a ZIP package.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-ckeditor-5-using-npm">

### Installing CKEditor 5 using npm

First, install the necessary package. The command below will install the main CKEditor 5 package containing all open-source plugins.

```
npm install ckeditor5

```

Now, you can import all the modules from the `ckeditor5` package. Additionally, you have to import CSS styles separately. Please note the [Essentials](../../../api/module%5Fessentials%5Fessentials-Essentials.html) plugin, including all essential editing features.

**Importing and registering UI translations is optional for American English.** To use the editor in any other language, use imported translations, as shown in the [setup section](#ckeditor5/latest/getting-started/setup/ui-language.html).

```
import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
        ],
        root: {
            placeholder: 'Type here...'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Import the selected [editor type](#ckeditor5/latest/getting-started/setup/editor-types.html) and plugins. Pass the imported plugins inside the configuration to the [create()](../../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#static-function-create) method and add toolbar items where applicable.

```
<div id="editor">
    <p>Hello from CKEditor 5!</p>
</div>

```

That is all the code you need to see a bare-bone editor running in your web browser.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-ckeditor-5-from-a-zip-file">

### Installing CKEditor 5 from a ZIP file

If you do not want to build your project using npm and cannot rely on the CDN delivery, you can download ready-to-run files with CKEditor 5 and all its plugins.

1. [Download the ZIP archive](https://cdn.ckeditor.com/ckeditor5/48.0.0/zip/ckeditor5-48.0.0.zip) with the latest CKEditor 5 distribution.
2. Extract the ZIP archive into a dedicated directory inside your project (for example, `vendor/`). Include the editor version in the directory name to ensure proper cache invalidation whenever you install a new version of CKEditor 5.

Files included in the ZIP archive:

* `index.html` – A sample with a working editor.
* `ckeditor5/ckeditor5.js` – The ready-to-use editor ESM bundle contains the editor and all plugins. \[Recommended build\]
* `ckeditor5/ckeditor.js.map` – The source map for the editor ESM bundle.
* `ckeditor5/ckeditor5.umd.js` – The ready-to-use editor UMD bundle contains the editor and all plugins. \[Secondary build\]
* `ckeditor5/ckeditor5.umd.js.map` – The source map for the editor UMD bundle.
* `ckeditor5/*.css` – The style sheets for the editor. You will use `ckeditor5.css` in most cases. Read about other files in the [Editor and content styles](#ckeditor5/latest/getting-started/setup/css.html) guide.
* `translations/` – The editor UI translations (see the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide).
* The `README.md` and `LICENSE.md` files.

The easiest way to see the editor in action is to serve the `index.html` file via an HTTP server.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-premium-features">

### Installing premium features

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-premium-features-using-npm">

#### Installing premium features using npm

All premium features are available as a separate package. You can install it the same as the open-source one.

```
npm install ckeditor5-premium-features

```

Now, you can import all the modules from both the `ckeditor5` and `ckeditor5-premium-features` packages. Additionally, you have to import CSS styles separately.

```
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Font } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Paragraph, Font, FormatPainter ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
            'formatPainter'
        ],
        root: {
            placeholder: 'Type here...'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Pass the imported plugins inside the configuration to the [create()](../../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#static-function-create) method and add toolbar items where applicable. Please note that to use premium features, you need to activate them with a proper license key. See the [Obtaining a license key](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--obtaining-a-premium-features-license-key) section.

```
<div id="editor">
    <p>Hello from CKEditor 5!</p>
</div>

```

That is all the code you need to see a bare-bone editor running in your web browser.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-premium-features-from-a-zip-file">

#### Installing premium features from a ZIP file

1. [Download the ZIP archive](https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/zip/ckeditor5-premium-features-48.0.0.zip) with the latest CKEditor 5 distribution and premium features.
2. Extract the ZIP archive into a dedicated directory inside your project (for example, `vendor/`). Include the editor version in the directory name to ensure proper cache invalidation whenever you install a new version of CKEditor 5.

Files in the ZIP archive:

* `index.html` – A sample with a working editor.
* The `ckeditor5/` directory:  
  * `ckeditor5.js` – The ready-to-use editor ESM bundle contains the editor and all plugins. \[Recommended build\]
  * `ckeditor.js.map` – The source map for the editor ESM bundle.
  * `ckeditor5.umd.js` – The ready-to-use editor UMD bundle contains the editor and all plugins. \[Secondary build\]
  * `ckeditor5.umd.js.map` – The source map for the editor UMD bundle.
  * `*.css` – The style sheets for the editor, use `ckeditor5.css` in most cases. Read about other files in the [Editor and content styles](#ckeditor5/latest/getting-started/setup/css.html) guide.
  * `translations/` – The editor UI translations (see the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide).
  * The `ckeditor5-premium-features/` directory:  
    * `ckeditor5-premium-features.js` – ESM bundle of premium features. \[Recommended build\]
    * `ckeditor5-premium-features.umd.js` – UMD bundle of premium features contains the editor and all plugins. \[Secondary build\]
    * `*.css` – The style sheets for the premium features. You will use `ckeditor5-premium-features.css` in most cases.
    * `translations/` – The premium features UI translations.
* The `ckeditor5-premium-features` directory is structured similarly to the `ckeditor5` directory. It contains equivalent files for premium features.
* The `README.md` and `LICENSE.md` files.

The easiest way to see the editor in action is to serve the `index.html` file via an HTTP server.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--obtaining-a-premium-features-license-key">

#### Obtaining a premium features license key

To activate CKEditor 5 premium features, you will need a commercial license. The easiest way to get one is to sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free) to test the premium features.

You can also [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs. To obtain an activation key, please follow the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html"</a>

## Integrating CKEditor 5 with React rich text editor component from npm

CKEditor 5 has an official React integration that you can use to add a rich text editor to your application. This guide will help you install it and configure to use the npm distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--quick-start">

### Quick start

This guide assumes that you already have a React project. If you do not have one, see the [React documentation](https://react.dev/learn/start-a-new-react-project) to learn how to create it.

First, install the CKEditor 5 packages:

* `ckeditor5` – package with open-source plugins and features.
* `ckeditor5-premium-features` – package with premium plugins and features.

Depending on your configuration and chosen plugins, you may need to install the first or both packages.

```
npm install ckeditor5 ckeditor5-premium-features

```

Then, install the [CKEditor 5 WYSIWYG editor component for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react):

```
npm install @ckeditor/ckeditor5-react

```

Use the `<CKEditor>` component inside your project. The below example shows how to use the component with open-source and premium plugins.

```
import { CKEditor } from '@ckeditor/ckeditor5-react';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

function App() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ],
                root: {
                    initialData: '<p>Hello from CKEditor 5 in React!</p>'
                },
            } }
        />
    );
}

export default App;

```

Remember to import the necessary style sheets. The `ckeditor5` package contains the styles for open-source features, while the `ckeditor5-premium-features` package contains the premium features styles.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--component-properties">

### Component properties

The `<CKEditor>` component supports the following properties:

* `editor` (required) – The [Editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) constructor to use.
* `data` – The initial data for the created editor. See the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* `config` – The editor configuration. See the [Configuration](#ckeditor5/latest/getting-started/setup/configuration.html) guide.
* `id` – The editor ID. When this property changes, the component restarts the editor with new data instead of setting it on an initialized editor.
* `disabled` – A Boolean value. The [editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) is being switched to read-only mode if the property is set to `true`.
* `disableWatchdog` – A Boolean value. If set to `true`, [the watchdog feature](#ckeditor5/latest/features/watchdog.html) will be disabled. It is set to `false` by default.
* `watchdogConfig` – [Configuration object](../../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) for the [watchdog feature](#ckeditor5/latest/features/watchdog.html).
* `onReady` – A function called when the editor is ready with an [editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) instance. This callback is also called after the reinitialization of the component if an error occurred.
* `onAfterDestroy` – A function called after the successful destruction of an editor instance rendered by the component. This callback is also triggered after the editor has been reinitialized after an error. The component is not guaranteed to be mounted when this function is called.
* `onChange` – A function called when the editor data has changed. See the [editor.model.document#change:data](../../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.
* `onBlur` – A function called when the editor was blurred. See the [editor.editing.view.document#blur](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.
* `onFocus` – A function called when the editor was focused. See the [editor.editing.view.document#focus](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.
* `onError` – A function called when the editor has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:  
  * `{String} phase`: `'initialization'|'runtime'` – Informs when the error has occurred (during the editor or context initialization, or after the initialization).
  * `{Boolean} willEditorRestart` – When `true`, it means that the editor component will restart itself.

The editor event callbacks (`onChange`, `onBlur`, `onFocus`) receive two arguments:

1. An [EventInfo](../../../../api/module%5Futils%5Feventinfo-EventInfo.html) object.
2. An [Editor](../../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html) instance.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--context-feature">

### Context feature

The [@ckeditor/ckeditor5-react](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) package provides a ready-to-use component for the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html) that is useful when used together with some [CKEditor 5 collaboration features](#ckeditor5/latest/features/collaboration/collaboration.html).

```
import { ClassicEditor, Context, Bold, Essentials, Italic, Paragraph, ContextWatchdog } from 'ckeditor5';
import { CKEditor, CKEditorContext } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

function App() {
  return (
    <CKEditorContext context={ Context } contextWatchdog={ ContextWatchdog }>
      <CKEditor
        editor={ ClassicEditor }
        config={ {
          licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
          plugins: [ Essentials, Bold, Italic, Paragraph ],
          toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        } }
        data='<p>Hello from the first editor working with the context!</p>'
        onReady={ ( editor ) => {
          // You can store the "editor" and use when it is needed.
          console.log( 'Editor 1 is ready to use!', editor );
        } }
      />

      <CKEditor
        editor={ ClassicEditor }
        config={ {
          licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
          plugins: [ Essentials, Bold, Italic, Paragraph ],
          toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        } }
        data='<p>Hello from the second editor working with the context!</p>'
        onReady={ ( editor ) => {
          // You can store the "editor" and use when it is needed.
          console.log( 'Editor 2 is ready to use!', editor );
        } }
      />
    </CKEditorContext>
  );
}

export default App;

```

The `CKEditorContext` component supports the following properties:

* `context` (required) – [The CKEditor 5 context class](../../../../api/module%5Fcore%5Fcontext-Context.html).
* `contextWatchdog` (required) – [The Watchdog context class](../../../../api/module%5Fwatchdog%5Fcontextwatchdog-ContextWatchdog.html).
* `config` – The CKEditor 5 context configuration.
* `isLayoutReady` – A property that delays the context creation when set to `false`. It creates the context and the editor children once it is `true` or unset. Useful when the CKEditor 5 annotations or a presence list are used.
* `id` – The context ID. When this property changes, the component restarts the context with its editor and reinitializes it based on the current configuration.
* `onChangeInitializedEditors` – A function called when any editor is initialized or destroyed in the tree. It receives a dictionary of fully initialized editors, where the key is the value of the `contextItemMetadata.name` property set on the `CKEditor` component. The editor’s ID is the key if the `contextItemMetadata` property is absent. Additional data can be added to the `contextItemMetadata` in the `CKEditor` component, which will be passed to the `onChangeInitializedEditors` function.
* `onReady` – A function called when the context is ready and all editors inside were initialized with the `context` instance. This callback is also called after the reinitialization of the component if an error has occurred.
* `onError` – A function called when the context has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:  
  * `{String} phase`: `'initialization'|'runtime'` – Informs when the error has occurred (during the editor or context initialization, or after the initialization).
  * `{Boolean} willContextRestart` – When `true`, it means that the context component will restart itself.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--using-the-document-editor-type">

#### Using the document editor type

If you use the [document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html), you need to [add the toolbar to the DOM manually](../../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create):

```
import { useEffect, useRef, useState } from 'react';
import { DecoupledEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

function App() {
    const editorToolbarRef = useRef( null );
    const [ isMounted, setMounted ] = useState( false );

    useEffect( () => {
        setMounted( true );

        return () => {
            setMounted( false );
        };
    }, [] );

    return (
        <div>
            <div ref={ editorToolbarRef }></div>
            <div>
                { isMounted && (
                    <CKEditor
                        editor={ DecoupledEditor }
                        data='<p>Hello from CKEditor 5 decoupled editor!</p>'
                        config={ {
                              licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                            plugins: [ Bold, Italic, Paragraph, Essentials ],
                            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
                        } }
                        onReady={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                editorToolbarRef.current.appendChild( editor.ui.view.toolbar.element );
                            }
                        }}
                        onAfterDestroy={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                Array.from( editorToolbarRef.current.children ).forEach( child => child.remove() );
                            }
                        }}
                    />
                ) }
            </div>
        </div>
    );
}

export default App;

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a few **ready-to-use integrations** featuring collaborative editing in React applications:

* [CKEditor 5 with real-time collaboration features and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-react)
* [CKEditor 5 with offline comments, track changes and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/collaboration-for-react)

It is not mandatory to build applications on top of the above samples, however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official React component. Follow the instructions below to translate CKEditor 5 in your React application.

Similarly to CSS style sheets, both packages have separate translations. Import them as shown in the example below. Then, pass them to the `translations` array inside the `config` prop in the CKEditor 5 component.

```
import { ClassicEditor } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';
// More imports...

import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';

function App() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                // ... Other configuration options ...
                translations: [ coreTranslations, premiumFeaturesTranslations ],
                root: {
                    initialData: '<p>Hola desde CKEditor 5 en React!</p>'
                }
            } }
        />
    );
}

export default App;

```

For more information, please refer to the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--jest-testing">

#### Jest testing

Jest is the default test runner used by many React apps. Unfortunately, Jest does not use a real browser. Instead, it runs tests in Node.js that uses JSDOM. JSDOM is not a complete DOM implementation, and while it is sufficient for standard apps, it cannot polyfill all the DOM APIs that CKEditor 5 requires.

For testing CKEditor 5, it is recommended to use testing frameworks that utilize a real browser and provide a complete DOM implementation. Some popular options include:

* [Vitest](https://vitest.dev/)
* [Playwright](https://playwright.dev/)
* [Cypress](https://www.cypress.io/)

These frameworks offer better support for testing CKEditor 5 and provide a more accurate representation of how the editor behaves in a real browser environment.

If this is not possible and you still want to use Jest, you can mock some of the required APIs. Below is an example of how to mock some of the APIs used by CKEditor 5:

```
import { TextEncoder } from 'util';
import React, { useRef } from 'react';
import { render, waitFor, screen } from '@testing-library/react';
import { userEvent } from '@testing-library/user-event';

import { DecoupledEditor, Essentials, Paragraph } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';

beforeAll( () => {
    window.TextEncoder = TextEncoder;

    window.scrollTo = jest.fn();

    window.ResizeObserver = class ResizeObserver {
        observe() {}
        unobserve() {}
        disconnect() {}
    };

    for ( const key of [ 'InputEvent', 'KeyboardEvent' ] ) {
        window[ key ].prototype.getTargetRanges = () => {
            const range = new StaticRange( {
                startContainer: document.body.querySelector( '.ck-editor__editable p' ),
                startOffset: 0,
                endContainer: document.body.querySelector( '.ck-editor__editable p' ),
                endOffset: 0
            } );

            return [ range ];
        };
    }

    const getClientRects = () => ({
        item: () => null,
        length: 0,
        [Symbol.iterator]: function* () {}
    });

    Range.prototype.getClientRects = getClientRects;
    Element.prototype.getClientRects = getClientRects;

    if ( !Document.prototype.createElementNS ) {
        Document.prototype.createElementNS = ( namespace, name ) => {
            const element = document.createElement( name );
            element.namespaceURI = namespace;
            return element;
        };
    }
} );

const SomeComponent = ( { value, onChange } ) => {
    const editorRef = useRef();

    return (
        <div
            style={{
                border: '1px solid black',
                padding: 10,
            }}
        >
            <CKEditor
                editor={ DecoupledEditor }
                config={{
                    plugins: [ Essentials, Paragraph ],
                }}
                onReady={ (editor) => {
                    editorRef.current = editor;
                } }
                data={ value }
                onChange={ () => {
                    onChange( editorRef.current?.getData() );
                } }
            />
        </div>
    );
};

it( 'renders', async () => {
    render( <SomeComponent value="this is some content" /> );

    await waitFor( () => expect( screen.getByText( /some content/ ) ).toBeTruthy());
} );

it( 'updates', async () => {
    const onChange = jest.fn();
    render( <SomeComponent value="this is some content" onChange={onChange} /> );

    await waitFor( () => expect( screen.getByText( /some content/ ) ).toBeTruthy() );

    await userEvent.click( document.querySelector( '[contenteditable="true"]' ) );

    userEvent.keyboard( 'more stuff' );

    await waitFor( () => expect( onChange ).toHaveBeenCalled() );
} );

```

The mocks presented above only test two basic scenarios, and more will likely need to be added, which may change with each version of the editor.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of rich text editor component for React is available on GitHub in <https://github.com/ckeditor/ckeditor5-react>.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html"</a>

## Integrating CKEditor 5 with React rich text multi-root editor hook from npm

This page focuses on describing the usage of the multi-root editor in React applications. If you would like to use a different type of editor, you can find more information [in this guide](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--quick-start">

### Quick start

This guide assumes you already have a React project. If you want to create a new one, you can use the [Vite](https://vitejs.dev/guide/) CLI. It allows you to create and customize your project with templates. For example, you can set up your project with TypeScript support.

Install the [CKEditor 5 WYSIWYG editor package for React](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) and the [multi-root editor type](#ckeditor5/latest/getting-started/setup/editor-types.html--multi-root-editor).

```
npm install ckeditor5 @ckeditor/ckeditor5-react

```

Use the `useMultiRootEditor` hook inside your project:

```
// App.jsx / App.tsx

import { MultiRootEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { useMultiRootEditor } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

const App = () => {
    const editorProps = {
        editor: MultiRootEditor,
        data: {
            intro: '<h1>React multi-root editor</h1>',
            content: '<p>Hello from CKEditor&nbsp;5 multi-root!</p>'
        },
        config: {
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
        }
    };

    const {
        editor,
        toolbarElement,
        editableElements,
        data,
        setData,
        attributes,
        setAttributes
    } = useMultiRootEditor( editorProps );

    return (
        <div className="App">
            <h2>Using CKEditor&nbsp;5 multi-root editor in React</h2>

            { toolbarElement }

            { editableElements }
        </div>
    );
}

export default App;

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--hook-properties">

### Hook properties

The `useMultiRootEditor` hook supports the following properties:

* `editor: MultiRootEditor` (required) – The [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) constructor to use.
* `data: Object` – The initial data for the created editor. See the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* `rootsAttributes: Object` – The initial roots attributes for the created editor.
* `config: Object` – The editor configuration. See the [Configuration](#ckeditor5/latest/getting-started/setup/configuration.html) guide.
* `disabled: Boolean` – The [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) is being switched to read-only mode if the property is set to `true`.
* `disableWatchdog: Boolean` – If set to `true`, [the watchdog feature](#ckeditor5/latest/features/watchdog.html) will be disabled. It is set to `false` by default.
* `watchdogConfig: WatchdogConfig` – [Configuration object](../../../../api/module%5Fwatchdog%5Fwatchdog-WatchdogConfig.html) for the [watchdog feature](#ckeditor5/latest/features/watchdog.html).
* `isLayoutReady: Boolean` – A property that delays the editor creation when set to `false`. It starts the initialization of the multi-root editor when sets to `true`. Useful when the CKEditor 5 annotations or a presence list are used.
* `disableTwoWayDataBinding: Boolean` – Allows disabling the two-way data binding mechanism between the editor state and `data` object to improve editor efficiency. The default value is `false`.
* `onReady: Function` – It is called when the editor is ready with a [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) instance. This callback is also called after the reinitialization of the component if an error occurred.
* `onChange: Function` – It is called when the editor data has changed. See the [editor.model.document#change:data](../../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) event.
* `onBlur: Function` – It is called when the editor was blurred. See the [editor.editing.view.document#blur](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) event.
* `onFocus: Function` – It is called when the editor was focused. See the [editor.editing.view.document#focus](../../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) event.
* `onError: Function` – It is called when the editor has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details.  
Error details is an object that contains two properties:  
  * `phase: 'initialization'|'runtime'` – Informs when an error has occurred (during the editor or context initialization, or after the initialization).
  * `willEditorRestart: Boolean` – If set to `true`, the editor component will restart itself.

The editor event callbacks (`onChange`, `onBlur`, `onFocus`) receive two arguments:

1. An [EventInfo](../../../../api/module%5Futils%5Feventinfo-EventInfo.html) object.
2. An [MultiRootEditor](../../../../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html) instance.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--hook-values">

### Hook values

The `useMultiRootEditor` hook returns the following values:

* `editor` – The instance of created editor.
* `toolbarElement` – `ReactElement` that contains the toolbar. It could be rendered anywhere in the application.
* `editableElements` – An array of `ReactElements` that describes the editor’s roots. This array is updated after detaching an existing root or adding a new root.
* `data` – The current state of the editor’s data. It is updated after each editor update. Note that you should not use it if you disabled two-way binding by passing the `disableTwoWayDataBinding` property.
* `setData` – The function used for updating the editor’s data.
* `attributes` – The current state of the editor’s attributes. It is updated after each editor attributes update. Note that you should not use it if you disabled two-way binding by passing the `disableTwoWayDataBinding` property.
* `setAttributes` – The function used for updating the editor’s attributes.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--context-feature">

### Context feature

The `useMultiRootEditor` hook also supports the [context feature](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html), as described in the main [React integration](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html--context-feature) guide.

However, as the multi-root editor addresses most use cases of the context feature, consider if you need to employ it.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--two-way-data-binding">

### Two-way data binding

By default, the two-way data binding is enabled. It means that every change done in the editor is automatically applied in the `data` object returned from the `useMultiRootEditor` hook. Additionally, if you want to change or set data in the editor, you can simply use `setData` method provided by the hook. It works the same way in case of attributes – the hook provides the `attributes` object and the `setAttributes` method to update them. It ensures that if you want to use or save the state of the editor, these objects are always up-to-date.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide several **ready-to-use integration** featuring collaborative editing with multi-root in React applications:

* [CKEditor 5 multi-root with real-time collaboration features and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-editor-multi-root-for-react)

It is not necessary to build applications on top of the above samples, however, they should help you get started.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of rich text editor component for React is available on GitHub in <https://github.com/ckeditor/ckeditor5-react>.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/react/react-multiroot-npm.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html"</a>

## Integrating CKEditor 5 with Salesforce from ZIP

Salesforce is a cloud-based Customer Relationship Management (CRM) platform that enables organizations to manage customer interactions, sales processes, and business operations. The platform supports custom development through its Lightning Platform (formerly Force.com), allowing developers to create custom objects, fields, pages, and components. While [CKEditor 5 does not support Shadow DOM yet](https://github.com/ckeditor/ckeditor5/issues/3891), which is required by Lightning modules, it can be integrated into Salesforce using [Visualforce pages](https://help.salesforce.com/s/articleView?id=platform.pages%5Fpages.htm&type=5). This integration approach enables rich text editing capabilities within Salesforce applications.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--prerequisites">

### Prerequisites

This section assumes you are working within the [Salesforce development platform](https://www.salesforce.com/form/developer-signup). We will guide you through creating a new Visualforce page that incorporates CKEditor 5\. Visualforce pages provide a way to create custom user interfaces in Salesforce using a markup language similar to HTML, making it an ideal solution for integrating third-party components like CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--creating-a-visualforce-page">

### Creating a Visualforce page

To start the integration, you need to create a new Visualforce page that will be used for the CKEditor 5 integration. Navigate to the _Setup_ page of your development platform and use the search input to find _Visualforce pages_.

Enter the Visualforce pages tab and add a new page by clicking the _New_ button. You should see a form that allows adding new pages, along with a code editor containing the default page markup.

Fill out the required fields in the form, check the _Available for Lightning Experience, Experience Builder sites, and the mobile app_ checkbox, then save the page. You are now ready to integrate the editor.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--integrating-ckeditor-5-in-visualforce-page-using-a-zip-archive">

### Integrating CKEditor 5 in Visualforce page using a ZIP archive

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--preparing-the-zip-package-with-ckeditor-5">

#### Preparing the ZIP package with CKEditor 5

Before starting the Salesforce integration, you need to prepare a ZIP package with CKEditor 5 that will be used inside your Visualforce page. CKEditor 5 offers an Online Builder that allows you to easily configure your editor through a user-friendly interface. The Online Builder provides a convenient way to select features, plugins, and customize the toolbar according to your specific requirements without writing any code.

To create your custom CKEditor 5 build, visit the [CKEditor 5 Online Builder](https://ckeditor.com/ckeditor-5/online-builder/). After configuring all the desired features and settings for your editor, you will reach the final step where you can choose your preferred technology and integration method. For Salesforce integration, select “Vanilla JavaScript” as your technology and “Self-hosted (ZIP)” as your integration method. This selection will generate and download a ZIP archive containing your customized editor.

The downloaded ZIP archive includes all the necessary files for integrating CKEditor 5 into your Salesforce Visualforce page, including the main JavaScript file, CSS styles, and sample implementation code. This package is ready for integration and does not require any additional build steps. Once you have your custom CKEditor 5 build, you can proceed with uploading these resources to Salesforce as static resources, which we will cover in the next section.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--uploading-ckeditor-5-files-as-static-resources">

#### Uploading CKEditor 5 files as static resources

To use CKEditor 5 in your Visualforce page, you need to upload the editor files as static resources in Salesforce. Static resources allow you to store assets like JavaScript files, CSS files, images, and other web resources that can be referenced in your Visualforce pages.

First, extract the downloaded ZIP package to access the `ckeditor5` directory containing `ckeditor5.umd.js` and `ckeditor5.css` files. After extraction, navigate to the Salesforce Setup page and search for “Static Resources” in the Quick Find box.

Click on “Static Resources” to open the Static Resources page. From there, click the “New” button to create a new static resource.

When creating a static resource for the JavaScript file, fill in the form with a name such as “CKEditor5JS” and an optional description like “CKEditor 5 JavaScript file”. Click “Choose File” to select the `ckeditor5.umd.js` file from your extracted package. For Cache Control, select “Public” to allow the browser to cache the resource. Click “Save” to upload the JavaScript file.

You will need to repeat this process for the CSS file. Create another static resource with a name like “CKEditor5CSS” and a description such as “CKEditor 5 CSS file”. Select the `ckeditor5.css` file and set Cache Control to “Public” before saving.

After uploading both files, they will appear in your Static Resources list and can be referenced in your Visualforce page.

Once your static resources are uploaded, you can reference them in your Visualforce page using the `$Resource` global variable with the `<apex:includeScript>` and `<apex:stylesheet>` tags, as shown in the next section.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--setting-up-the-page-structure">

#### Setting up the page structure

Visualforce pages use a markup language similar to HTML, but with special tags prefixed with `apex:`. Every Visualforce page must be wrapped in an `<apex:page>` tag, which serves as the root element. This tag can include various attributes to control the page’s behavior, such as `docType`, `showHeader`, and `standardStylesheets`. Inside this wrapper, you can use standard HTML elements along with Visualforce-specific components to build your page layout and functionality.

For our CKEditor 5 integration, we will use a basic page structure that includes necessary JavaScript and CSS resources, along with a container for the editor. The page markup will look similar to this:

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Resources will be added here -->
    </head>
    <body>
        <!-- Editor container will be added here -->
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--adding-ckeditor-5-static-resources">

#### Adding CKEditor 5 static resources

We will start from adding resources required for running CKEditor 5 (CSS and JavaScript) to the `<head>` tag using the static resources we uploaded in the previous step. We will use Visualforce’s `<apex:includeScript>` and `<apex:stylesheet>` tags to reference these resources:

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Load CKEditor&nbsp;5 JavaScript and CSS from static resources -->
        <apex:includeScript value="{!$Resource.CKEditor5JS}"/>
        <apex:stylesheet value="{!$Resource.CKEditor5CSS}"/>
    </head>
    <body>
        <!-- Editor container will be added here -->
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--initializing-the-editor">

#### Initializing the editor

Now, we can add the container that will hold our editor and introduce an initialization script with the basic editor configuration:

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- JavaScript and CSS resources-->
    </head>
    <body>
        <!-- Editor container -->
         <div id="editor" style="min-height: 300px; border: 1px solid #ccc;"></div>

         <!-- Initialization script -->
          <script type="module">
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>' // Or 'GPL',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
       </script>
    </body>
</apex:page>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--complete-integration-code">

#### Complete integration code

Putting everything together, the full integration code looks as follows (remember to insert your license key in the editor configuration):

```
<apex:page showHeader="false" standardStylesheets="false" docType="html-5.0">
    <head>
        <!-- Load CKEditor&nbsp;5 JavaScript and CSS from static resources -->
        <apex:includeScript value="{!$Resource.CKEditor5JS}"/>
        <apex:stylesheet value="{!$Resource.CKEditor5CSS}"/>
    </head>
    <body>
        <!-- Editor container -->
         <div id="editor" style="min-height: 300px; border: 1px solid #ccc;">CKEditor&nbsp;5 integration with Salesforce.</div>

         <!-- Initialization script -->
          <script type="module">
            const {
                ClassicEditor,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } = CKEDITOR;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>' // Or 'GPL',
                    plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ]
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</apex:page>

```

Now, you can save your component and click the _Preview_ button to see it live. A new page should open in your browser, and you should see the CKEditor 5 instance:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--using-ckeditor-5-visualforce-component-in-lightning-page">

### Using CKEditor 5 Visualforce component in Lightning page

Now that we have created our CKEditor 5 Visualforce page, we can embed it into a Lightning page. This process involves adding the Visualforce page as a component within your Lightning page layout. To do this, navigate to the Lightning App Builder, where you can drag and drop the Visualforce page component onto your desired location in the page layout. The editor will be displayed within an iframe, maintaining its full functionality while being seamlessly integrated into your Lightning page.

Let’s go through the steps to add our CKEditor 5 component to a Lightning page:

To add your CKEditor 5 component to a Lightning page, first navigate to the Lightning App Builder. Once there, either select an existing Lightning page or create a new one where you want to incorporate the editor. Next, locate the Visualforce page component in the components panel and add it to your desired position in the layout. After adding the component, configure its settings and specifically select your CKEditor 5 component from the available options. Finally, save your changes and activate the Lightning page to make it available to users.

You should end up with something similar to this:

Now, you can view your Lightning page and use your editor:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--distributing-your-ckeditor-5-component">

### Distributing your CKEditor 5 component

To make your CKEditor 5 Visualforce component available to other Salesforce users, you can create a package. This allows you to distribute your component as a standalone solution that can be easily installed in other Salesforce environments.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--creating-a-package">

#### Creating a package

To create a package, navigate to the Salesforce Setup page and use the Quick Find box to search for _Packages_. Click the _New_ button to start creating your package. In the package creation form, provide a meaningful name like “CKEditor 5 Integration” and a clear description that explains the purpose of your component. Set the initial version to “1.0” and consider selecting “Managed Package” if you want to maintain control over future updates. This option allows you to push updates to all installations of your package.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--adding-components-to-the-package">

#### Adding components to the package

After creating the package, you will need to add your CKEditor 5 Visualforce page to it. In the package details page, use the _Add_ button to include new components. Select “Visualforce Page” from the component type dropdown and choose your CKEditor 5 Visualforce page from the list. This will include all the necessary code and resources in your package.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--uploading-the-package">

#### Uploading the package

Once you have added all required components, you can upload your package. The upload process involves choosing whether to make the package public or private. Public packages are visible in the Salesforce AppExchange, while private packages are only accessible via direct installation links. After selecting the visibility option and accepting the terms and conditions, click _Upload_ to make your package available for distribution.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--installing-the-package">

#### Installing the package

After the upload is complete, you will receive an installation URL that looks like this:

```
https://login.salesforce.com/packaging/installPackage.apexp?p0=04td20000002WVF&isdtp=p1

```

Users can install your package by logging into their Salesforce account and visiting this URL. The installation process will guide them through granting necessary permissions and configuring the component in their environment.

After installation, users can add the CKEditor 5 component to their Lightning pages following the steps described in the [Using CKEditor 5 Visualforce component in Lightning page](#ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--using-ckeditor-5-visualforce-component-in-lightning-page) section.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/salesforce.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html"</a>

## Integrating CKEditor 5 rich-text editor with SharePoint SPFx from npm

[The SharePoint Framework (SPFx)](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) is Microsoft’s modern, client-side development model for building custom experiences that run in the SharePoint Online, Microsoft Teams, Viva Connections, Outlook, and the Microsoft 365 applications.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--prerequisites">

### Prerequisites

Before integrating CKEditor 5 rich-text editor with SharePoint, make sure you have the following installed:

1. [Node.js](https://nodejs.org/) (LTS version)
2. [Yeoman generator](https://yeoman.io/) and SharePoint generator plugin:

```
npm install -g yo @microsoft/generator-sharepoint

```

1. [Gulp](https://gulpjs.com/) (for building the project):

```
npm install -g gulp

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--creating-a-new-web-part-project">

### Creating a new web part project

First, create a new folder and navigate into it:

```
mkdir my-spfx-app
cd my-spfx-app

```

Generate a new SPFx web part project:

```
yo @microsoft/sharepoint

```

When prompted for:

* **Which type of client-side component to create?** – choose WebPart
* **Which template would you like to use?** – choose React

You will be also prompted for names for the application and the web part, for example:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--running-the-web-part-project">

### Running the web part project

After the project is created, go to `config/serve.json` file and update the `initialPage` property with your SharePoint tenant URL:

```
"initialPage": "https://your-tenant.sharepoint.com/_layouts/workbench.aspx"

```

At this point you should be able to run the project by executing:

```
gulp serve

```

A new browser tab with SPFx app should open automatically. You might be prompted to log in to your Microsoft account at this point.

If the page does not open automatically, navigate to the following URL:

```
https://your-tenant.sharepoint.com/_layouts/workbench.aspx

```

If everything went fine, you should see a screen similar to this one:  

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--ckeditor-5-web-part-integration">

### CKEditor 5 web part integration

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--installing-dependencies">

#### Installing dependencies

Now it is time to add CKEditor 5 to the application. First, install CKEditor 5 and React integration packages:

```
npm install --save @ckeditor/ckeditor5-react ckeditor5 ckeditor5-premium-features

```

In `tsconfig.json` file add:

```
...
"allowSyntheticDefaultImports": true
...

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--creating-ckeditor-5-web-part-component">

#### Creating CKEditor 5 web part component

Assuming you named your web part “RichTextEditor”, open the `src/webparts/richTextEditor/components/RichTextEditor.tsx` file and modify it to include CKEditor 5:

```
import * as React from 'react';
import type { IRichTextEditorProps } from './IRichTextEditorProps';
import { CKEditor } from '@ckeditor/ckeditor5-react';

import {
    ClassicEditor,
    Bold,
    Essentials,
    Italic,
    Paragraph,
    Font,
    Heading,
    Table,
    List,
    TableCellProperties,
    TableProperties,
    TableToolbar,
    Autoformat
} from 'ckeditor5';

import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

export default class RichTextEditor extends React.Component<IRichTextEditorProps> {
    public render(): React.ReactElement<IRichTextEditorProps> {
        return (
                <CKEditor
                        editor={ ClassicEditor }
                        config={ {
                                licenseKey: '<YOUR_LICENSE_KEY>',
                                plugins: [
                                    Bold, Essentials, Italic, Paragraph, Font, Heading,
                                    Table, TableCellProperties, TableProperties, TableToolbar, List,
                                    Autoformat, FormatPainter
                                ],
                                toolbar: [
                                    'undo', 'redo', '|', 'bold', 'italic', '|',
                                    'fontFamily', 'fontSize', 'fontColor', 'fontBackgroundColor', '|',
                                    'formatPainter', 'insertTable', 'bulletedList', 'numberedList'
                                ],
                                root: {
                                    initialData: '<p>Hello from CKEditor 5 in SPFX React app!</p>'
                                },
                                table: {
                                    contentToolbar: [
                                        'tableColumn', 'tableRow', 'mergeTableCells',
                                        'tableProperties', 'tableCellProperties'
                                    ]
                                }
                        } }
                />
        );
    }
}

```

Restart the server and then refresh the page.

```
gulp serve

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--adding-the-editor-web-part-on-page">

#### Adding the editor web part on page

You should be now able to add CKEditor 5 HTML editor to your SharePoint application by clicking the plus icon on the main page:

Then choose CKEditor 5 component:

You should now be able to use the rich-text editor with SharePoint:

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--known-issues">

### Known issues

* When using Rooster JS React in SharePoint with the SPFx Framework, after inserting a link, the Enter key may stop working. Adding `data-sp-a11y-skipkeys='all'` in the div wrapping the editor should fix the problem. (See [issue](https://github.com/SharePoint/sp-dev-docs/issues/9438)).
* When using CKEditor 5 inside a Fluent UI `Dialog` or `Modal` component, image resizing handles might not work because the `Layer` component captures mouse events. To fix this, enable event bubbling in the `modalProps`:

```
<Dialog
    modalProps={ {
        layerProps: {
            // Enable event bubbling to allow CKEditor 5 resize handles to work.
            eventBubblingEnabled: true
        }
    } }
>
    {/* ... */}
</Dialog>

```

* SharePoint overrides the table border styles. This is a problem since SharePoint uses the following style:

```
.ck-content .table > table {
    border: unset !important;
}

```

The `!important` rule overrides any styles generated by the editor, so setting them through table properties has no effect. To fix it, you need to make sure CKEditor 5’s internal styles take precedence before SharePoint’s global styles. This can be achieved by introducing the following workaround in the form of a custom plugin:

```
/**
* CKEditor 5 Plugin defined as a simple function.
* Forces !important on table border styles to override SharePoint CSS.
*/

const ForceTableBorderImportant = ( editor: Editor ) => {
    const { view } = editor.editing;
    const modifiedElements = new Set<ViewElement>();

    const BORDER_ATTRIBUTES = [
        'borderColor', 'borderWidth', 'borderStyle',
        'tableBorderColor', 'tableBorderWidth', 'tableBorderStyle'
    ];

    /**
     * Resolves the actual DOM element that needs styling.
     */
    const resolveTargetDomElement = ( viewElement: ViewElement, domConverter: ViewDomConverter ): HTMLElement | null | undefined => {
        const domElement = domConverter.mapViewToDom( viewElement );
        return domElement?.matches( 'table' ) ? domElement : domElement?.querySelector( 'table' );
    };

    /**
    * Extracts default border properties from the editor configuration.
    */
    const getDefaultBorderConfig = () => {
        const config = editor.config.get( 'table.tableProperties.defaultProperties' );
        return {
            width: config?.borderWidth || '1px',
            style: config?.borderStyle || 'double',
            color: config?.borderColor || '#b3b3b3'
        };
    };

    /**
    * Applies default border values if missing and enforces !important on all border styles.
    */
    const enforceBorderStyles = ( domElement: HTMLElement, defaults: { width: string, style: string, color: string } ) => {
    // Skip layout tables (used for positioning, not data)
    if (
        domElement.closest('figure')?.classList.contains( 'layout-table' ) ||
        domElement.classList.contains( 'layout-table' )
    ) {
        return;
    }

    const style = domElement.style;

    // 1. Apply default values only if specific properties are missing.
    if ( !style.getPropertyValue( 'border-width' ) ) style.setProperty( 'border-width', defaults.width, 'important' );
    if ( !style.getPropertyValue( 'border-style' ) ) style.setProperty( 'border-style', defaults.style, 'important' );
    if ( !style.getPropertyValue( 'border-color' ) ) style.setProperty( 'border-color', defaults.color, 'important' );

    // 2. Iterate through ALL active border-related properties and enforce !important.
    Array.from( style )
        .filter( propName => propName.includes( 'border' ) )
        .forEach( propName => {
            if ( style.getPropertyPriority( propName ) !== 'important' ) {
                style.setProperty( propName, style.getPropertyValue( propName ), 'important' );
            }
        } );
    };

    // 1. Collection Phase (Downcast)
    editor.conversion.for( 'editingDowncast' ).add( ( dispatcher: any ) => {
        const addToCollection = ( evt: unknown, data: any, { mapper }: any ) => {
            const viewElement = mapper.toViewElement( data.item );
            if ( viewElement ) {
                modifiedElements.add( viewElement );
            }
    };

    BORDER_ATTRIBUTES.forEach( attr =>
        dispatcher.on( `attribute:${ attr }`, addToCollection, { priority: 'lowest' } )
    );
    } );

    // 2. Execution Phase (Render)
    view.on( 'render', () => {
        if ( !modifiedElements.size ) return;

        const defaultBorder = getDefaultBorderConfig();

        modifiedElements.forEach( viewElement => {
            const domElement = resolveTargetDomElement( viewElement, view.domConverter );
            if ( domElement ) {
                enforceBorderStyles( domElement, defaultBorder );
            }
        } );

        modifiedElements.clear();
    } );
};

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--additional-resources">

### Additional resources

* [SharePoint Framework Documentation](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview)
* [React integration documentation](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html)

<a id="ckeditor5/latest/getting-started/installation/self-hosted/sharepoint.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html"</a>

## Integrating CKEditor 5 with Spring Boot from ZIP

As a pure JavaScript/TypeScript application, CKEditor 5 will work inside any environment that supports such components. While we do not offer official integrations for any non-JavaScript frameworks, you can include a custom configuration of CKEditor 5 rich-text editor in a non-JS framework of your choice, for example, the Java-based [Spring Boot](https://spring.io/projects/spring-boot).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html--setting-up-the-project">

### Setting up the project

This guide assumes you already have a Spring Boot project. You can create a basic Spring Boot project using [Spring Initializr](https://start.spring.io/). Refer to the [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html) to learn how to set up a project in this framework.

This guide is using the “Spring Web” and “Thymeleaf” dependencies selected in the Spring Initializr. Here is the list of dependencies used in the demo project:

```
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
</dependencies>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html--integrating-using-zip">

### Integrating using ZIP

After downloading and unpacking the ZIP archive, copy the `ckeditor5.js` and `ckeditor5.css` files into the `src/main/resources/static/ckeditor5/` directory. The folder structure of your app should resemble this one.

```
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com
│   │   │       └── example
│   │   │           └── demo
│   │   │               └── DemoApplication.java
│   │   └── resources
│   │       ├── static
│   │       │   ├── ckeditor5
│   │       │   │   ├── ckeditor5.js
│   │       │   │   └── ckeditor5.css
│   │       │   └── ...
│   │       ├── templates
│   │       │   ├── ckeditor5.html
│   │       │   └── ...
│   │       └── application.properties
│   └── test
├── pom.xml
└── ...

```

Having all the dependencies of CKEditor 5, create or modify the `index.html` file in the `src/main/resources/templates` directory to import them. All the necessary markup is in the `index.html` file from the ZIP archive. You can copy and paste it into your template. Pay attention to the paths of the import map and CSS link – they should reflect your folder structure. The template should look similar to the one below:

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>CKEditor 5 - Spring Boot Integration</title>
        <link rel="stylesheet" href="/assets/vendor/ckeditor5.css">
        <style>
            .main-container {
                width: 795px;
                margin-left: auto;
                margin-right: auto;
            }
        </style>
    </head>
    <body>
        <div class="main-container">
            <div id="editor">
                <p>Hello from CKEditor 5!</p>
            </div>
        </div>
        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "./ckeditor5/ckeditor5.js",
                    "ckeditor5/": "./ckeditor5/"
                }
            }
        </script>
        <script type="module">
            import {
                ClassicEditor,
                Essentials,
                Paragraph,
                Bold,
                Italic,
                Font
            } from 'ckeditor5';

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    plugins: [ Essentials, Paragraph, Bold, Italic, Font ],
                    toolbar: [
                        'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ]
                } )
                .then( editor => {
                    window.editor = editor;
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

To make the HTML editor work with Spring Boot, you need to create a controller to serve the HTML page. Create a file named `HomeController.java` in your project’s main package:

```
package com.example.demo;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class HomeController {

    @GetMapping("/")
    public String home() {
        return "index";
    }
}

```

Finally, run your Spring Boot application using `./mvnw spring-boot:run` (or `mvnw.cmd spring-boot:run` on Windows) and navigate to `http://localhost:8080` to see the editor in action.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/spring-boot.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/svelte.html"</a>

## Integrating CKEditor 5 with Svelte from npm

[Svelte](https://svelte.dev/) is a modern JavaScript compiler that builds highly optimized, reactive web applications. Unlike traditional frameworks, Svelte shifts most of the work from runtime to build time, resulting in highly efficient applications. CKEditor 5 rich-text editor can be easily integrated with Svelte applications, providing powerful rich text editing capabilities to your projects.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--quick-start">

### Quick start

This guide will show you how to integrate CKEditor 5 into a Svelte application using the npm distribution. If you are new to Svelte, check out their [official tutorial](https://svelte.dev/docs/svelte/getting-started).

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--setting-up-a-svelte-project">

#### Setting up a Svelte project

First, create a new Svelte project using Vite:

```
npm create vite@latest ckeditor-svelte -- --template svelte
cd ckeditor-svelte
npm install

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--installing-ckeditor-5">

#### Installing CKEditor 5

Next, install the `ckeditor5` and the `ckeditor5-premium-features` packages:

```
npm install ckeditor5 ckeditor5-premium-features

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--project-structure">

#### Project structure

When completed, the folder structure of your project should resemble this one:

```
├── node_modules/
├── public/
├── src/
│   ├── lib/
│   │   └── Editor.svelte
│   ├── App.svelte
│   ├── main.js
│   └── ...
├── index.html
├── package.json
├── vite.config.js
├── svelte.config.js
└── ...

```

The integration requires two key Svelte components:

* `src/lib/Editor.svelte` – the component that wraps CKEditor functionality
* `src/App.svelte` – the main application component that uses the Editor component

Let’s implement these components next.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--implementing-the-editor-component">

#### Implementing the Editor component

Create a new file `src/lib/Editor.svelte` with the following content:

```
<script>
    import { onMount, onDestroy } from 'svelte';

    import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from 'ckeditor5';
    import { FormatPainter } from 'ckeditor5-premium-features';

    import 'ckeditor5/ckeditor5.css';
    import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

    let { value = $bindable('') } = $props();

    let editorContainer;
    let editorInstance = $state(null);
    let isDestroyed = false;

    // Sync external value changes to the editor.
    $effect(() => {
        if (editorInstance && editorInstance.getData() !== value) {
            editorInstance.setData(value);
        }
    });

    onMount( async () => {
        // Capture value before async initialization.
        let initialData = value;

        editorInstance = await ClassicEditor.create( {
            attachTo: editorContainer,
            licenseKey: '<YOUR_LICENSE_KEY>', // Replace with your license key
            plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ],
            toolbar: [
                'undo', 'redo', '|', 'bold', 'italic', '|',
                'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
                'formatPainter'
            ],
            initialData
        } );

        // Prevent memory leaks if unmounted during creation.
        if (isDestroyed) {
            await editorInstance.destroy();
            return;
        }

        // Update the bound value when editor content changes.
        editorInstance.model.document.on( 'change:data', () => {
            value = editorInstance.getData();
        } );
    } );

    onDestroy( () => {
        // Clean up editor instance on unmount.
        editorInstance?.destroy().catch( err => console.error( err ) );
        editorInstance = null;
        isDestroyed = true;
    } );
</script>

<div bind:this={editorContainer}></div>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--using-the-editor-component">

#### Using the Editor component

Now, modify the main `App.svelte` file to use our editor component:

```
<script>
    import Editor from './lib/Editor.svelte';

    let content = $state('<p>Enter your content here...</p>');
</script>

<main>
    <h1>CKEditor 5 + Svelte</h1>

    <div class="editor-wrapper">
        <Editor bind:value={content} />
    </div>
</main>

<style>
    .editor-wrapper {
        width: 800px;
    }

    :global(.ck.ck-editor__editable) {
        height: 200px;
        background-color: white;
        color: #333;
    }
</style>

```

You can now run the dev server to see the editor in action:

```
npm run dev

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--component-structure">

#### Component structure

The Svelte HTML editor integration follows these key steps:

1. **Import dependencies**: The required CKEditor 5 modules and styles are imported.
2. **Editor initialization**: The editor is created with the specified configuration when the component mounts.
3. **Two-way data binding**: The editor listens to `change:data` events on `editor.model.document` to update the bound value, while a Svelte `$effect` syncs external value changes back to the editor.
4. **Cleanup**: Resources are properly released when the component is destroyed.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--styling">

#### Styling

Basic styling is provided in the `App.svelte` component to ensure proper display in various environments, especially when using dark themes:

```
.editor-wrapper {
    width: 800px;
}

:global(.ck.ck-editor__editable) {
    height: 200px;
    background-color: white;
    color: #333;
}

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/svelte.html--next-steps">

### Next steps

* Explore the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide to learn how to handle content.
* Learn more about [configuration options](#ckeditor5/latest/getting-started/setup/configuration.html) to customize your editor.
* Check the [features documentation](#ckeditor5/latest/features/index.html) to add more functionality to your editor.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html"</a>

## Integrating CKeditor 5 with Vue.js 2.x from npm

You can use CKEditor 5 Vue 2 component to add a rich text editor to your application. This guide will help you install and configure the npm distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--quick-start">

### Quick start

This guide assumes you already have a Vue project. First, install the CKEditor 5 packages:

* `ckeditor5` – package with open-source plugins and features.
* `ckeditor5-premium-features` – package with premium plugins and features.

```
npm install ckeditor5 ckeditor5-premium-features

```

Depending on your configuration and chosen plugins, you may need to install the first or both packages.

Then, install the [CKEditor 5 WYSIWYG editor component for Vue 2](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue2):

```
npm install @ckeditor/ckeditor5-vue2

```

To create an editor instance, you must first import the editor and the component modules into the root file of your application (for example, `main.js` when generated by `create-vue`).

```
import Vue from 'vue';
import CKEditor from '@ckeditor/ckeditor5-vue2';
import App from './App.vue';

Vue.use( CKEditor );

new Vue( App ).$mount( '#app' );

```

Use the `<ckeditor>` component inside the template tag. The below example shows how to use the component with open-source and premium plugins.

```
<template>
    <ckeditor :editor="editor" v-model="editorData" :config="editorConfig" />
</template>

<script>
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

export default {
    name: 'app',
    data() {
        return {
            editor: ClassicEditor,
            editorData: '<p>Hello from CKEditor 5 in Vue 2!</p>',
            editorConfig: {
                licenseKey: '<YOUR_LICENSE_KEY>',
                plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
            }
        };
    }
};
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--using-the-component-locally">

#### Using the component locally

If you do not want the CKEditor component to be enabled globally, you can skip the `Vue.use( CKEditor )` part entirely. Instead, configure it in the `components` property of your view.

```
<template>
    <ckeditor :editor="editor" v-model="editorData" :config="editorConfig" />
</template>

<script>
import CKEditor from '@ckeditor/ckeditor5-vue2';
import { Bold, ClassicEditor, Essentials, Italic, Paragraph } from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

export default {
    name: 'app',
    components: {
        ckeditor: CKEditor.component
    },
    data() {
        return {
            editor: ClassicEditor,
            editorData: '<p>Hello from CKEditor 5 in Vue 2!</p>',
            editorConfig: {
                licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                plugins: [ Bold, Essentials, Italic, Paragraph ],
                toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
            }
        };
    }
};
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--component-directives">

### Component directives

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--editor">

#### `editor`

This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.

```
<template>
    <ckeditor :editor="editor" />
</template>

<script>
    import { ClassicEditor } from 'ckeditor5';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,

                // ...
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--tag-name">

#### `tag-name`

By default, the editor component creates a `<div>` container which is used as an element passed to the editor (for example, [ClassicEditor#element](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html#member-element)). The element can be configured, so for example to create a `<textarea>`, use the following directive:

```
<ckeditor :editor="editor" tag-name="textarea" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--v-model">

#### `v-model`

A [standard directive](https://vuejs.org/v2/api/#v-model) for form inputs in Vue. Unlike [value](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--value), it creates a two–way data binding, which:

* Sets the initial editor content.
* Automatically updates the state of the application as the editor content changes (for example, as the user types).
* Can be used to set the editor content when necessary.

```
<template>
    <div>
        <ckeditor :editor="editor" v-model="editorData" />
        <button v-on:click="emptyEditor()">Empty the editor</button>

        <h2>Editor data</h2>
        <code>{{ editorData }}</code>
    </div>
</template>

<script>
    import { ClassicEditor } from 'ckeditor5';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        },
        methods: {
            emptyEditor() {
                this.editorData = '';
            }
        }
    };
</script>

```

In the above example, the `editorData` property will be updated automatically as the user types and changes the content. It can also be used to change (as in `emptyEditor()`) or set the initial content of the editor.

If you only want to execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--value">

#### `value`

Allows a one–way data binding that sets the content of the editor. Unlike [v-model](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--v-model), the value will not be updated when the content of the editor changes.

```
<template>
    <ckeditor :editor="editor" :value="editorData" />
</template>

<script>
    import { ClassicEditor } from 'ckeditor5';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        }
    };
</script>

```

To execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--config">

#### `config`

Specifies the [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor.

```
<template>
    <ckeditor :editor="editor" :config="editorConfig" />
</template>

<script>
    import { ClassicEditor } from 'ckeditor5';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorConfig: {
                    toolbar: [ 'bold', 'italic', '|', 'link' ]
                }
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--disabled">

#### `disabled`

This directive controls the [isReadOnly](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property of the editor.

It sets the initial read–only state of the editor and changes it during its lifecycle.

```
<template>
    <ckeditor :editor="editor" :disabled="editorDisabled" />
</template>

<script>
    import { ClassicEditor } from 'ckeditor5';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                // This editor will be read–only when created.
                editorDisabled: true
            };
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--component-events">

### Component events

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--ready">

#### `ready`

Corresponds to the [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) editor event.

```
<ckeditor :editor="editor" @ready="onEditorReady" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--focus">

#### `focus`

Corresponds to the [focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) editor event.

```
<ckeditor :editor="editor" @focus="onEditorFocus" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--blur">

#### `blur`

Corresponds to the [blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) editor event.

```
<ckeditor :editor="editor" @blur="onEditorBlur" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--input">

#### `input`

Corresponds to the [change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) editor event. See the [v-model directive](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--v-model) to learn more.

```
<ckeditor :editor="editor" @input="onEditorInput" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--destroy">

#### `destroy`

Corresponds to the [destroy](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-destroy) editor event.

**Note:** Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.

```
<ckeditor :editor="editor" @destroy="onEditorDestroy" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--using-the-document-editor-type">

#### Using the Document editor type

If you use the [Document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html) in your application, you need to [manually add the editor toolbar to the DOM](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create).

Since accessing the editor toolbar is not possible until after the editor instance is [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready), put your toolbar insertion code in a method executed upon the [ready](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--ready) event of the component, like in the following example:

```
<template>
    <ckeditor :editor="editor" @ready="onReady" />
</template>

<script>
    import { DecoupledEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';

    import 'ckeditor5/ckeditor5.css'

    export default {
        name: 'app',
        data() {
            return {
                editor: DecoupledEditor,
                // ...
            };
        },
        methods: {
            onReady( editor )  {
                // Insert the toolbar before the editable area.
                editor.ui.getEditableElement().parentElement.insertBefore(
                    editor.ui.view.toolbar.element,
                    editor.ui.getEditableElement()
                );
            }
        }
    };
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official Vue 2 component. Follow the instructions below to translate CKEditor 5 in your Vue application.

Similarly to CSS style sheets, both packages have separate translations. Import them as shown in the example below. Then, pass them to the `translations` array inside the `editorConfig` prop in the component.

```
<template>
    <ckeditor :editor="editor" v-model="editorData" :config="editorConfig" />
</template>

<script>
import { ClassicEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
// More imports...

import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';

export default {
    name: 'app',
    data() {
        return {
            editor: ClassicEditor,
            editorData: '<p>Hola desde CKEditor 5 en Vue 2!</p>',
            editorConfig: {
                // ... Other configuration options ...
                translations: [ coreTranslations, premiumFeaturesTranslations ]
            }
        };
    }
};
</script>

```

For more information, refer to the [“Setting UI language”](#ckeditor5/latest/getting-started/setup/ui-language.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of this component is available on GitHub in <https://github.com/ckeditor/ckeditor5-vue2>.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v2.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html">source file: "ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html"</a>

## Integrating CKEditor 5 with Vue.js 3+ from npm

CKEditor 5 has an official Vue integration that you can use to add a rich text editor to your application. This guide will help you install it and configure to use the npm distribution of the CKEditor 5.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--quick-start">

### Quick start

This guide assumes that you already have a Vue project. If you do not have one, see the [Vue documentation](https://vuejs.org/guide/quick-start) to learn how to create it.

Start by installing the following packages:

`ckeditor5` – contains all open-source plugins and features for CKEditor 5.

```
npm install ckeditor5

```

`ckeditor5-premium-features` – contains premium plugins and features for CKEditor 5\. Depending on your configuration and chosen plugins, you might not need it.

```
npm install ckeditor5-premium-features

```

`@ckeditor/ckeditor5-vue` – the [CKEditor 5 WYSIWYG editor component for Vue](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue).

```
npm install @ckeditor/ckeditor5-vue

```

With these packages installed, create a new Vue component called `Editor.vue`. It will use the `<ckeditor>` component to run the editor. The following example shows a single file component with open-source and premium CKEditor 5 plugins.

```
<template>
    <ckeditor
        v-model="data"
        :editor="ClassicEditor"
        :config="config"
    />
</template>

<script setup>
import { ref, computed } from 'vue';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { FormatPainter } from 'ckeditor5-premium-features';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

const data = ref( '<p>Hello world!</p>' );

const config = computed( () => {
    return {
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'formatPainter' ]
    };
} );
</script>

```

Now, you can import and use the `Editor.vue` component anywhere in your application.

```
<template>
    <Editor />
</template>

```

If you use Nuxt.js with server-side rendering enabled, remember to wrap the `<Editor>` component in the `<ClientOnly>` component to avoid issues with the editor calling browser-specific APIs on the server.

```
<template>
    <ClientOnly>
        <Editor />
    </ClientOnly>
</template>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--component-directives">

### Component directives

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--editor">

#### `editor`

This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.

```
<template>
    <ckeditor :editor="ClassicEditor" />
</template>

<script setup>
import { ClassicEditor } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--tag-name">

#### `tag-name`

By default, the editor component creates a `<div>` container which is used as an element passed to the editor (for example, [ClassicEditor#element](../../../api/module%5Feditor-classic%5Fclassiceditorui-ClassicEditorUI.html#member-element)). The element can be configured, so for example to create a `<textarea>`, use the following directive:

```
<ckeditor :editor="editor" tag-name="textarea" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--v-model">

#### `v-model`

A [standard directive](https://v3.vuejs.org/guide/component-basics.html#using-v-model-on-components) for form inputs in Vue. Unlike [model-value](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--model-value), it creates a two–way data binding, which:

* Sets the initial editor content.
* Automatically updates the state of the application as the editor content changes (for example, as the user types).
* Can be used to set the editor content when necessary.

```
<template>
    <ckeditor :editor="ClassicEditor" v-model="data" />
    <button @click="emptyEditor">Empty the editor</button>

    <h2>Editor data</h2>
    <code>{{ data }}</code>
</template>

<script setup>
import { ref } from 'vue';
import { ClassicEditor } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

const data = ref( '<p>Hello world!</p>' );

function emptyEditor() {
    data.value = '';
}
</script>

```

In the above example, the `data` property will be updated automatically as the user types and the content changes. It can also be used to change (as in `emptyEditor()`) or set the initial content of the editor.

If you only want to execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--model-value">

#### `model-value`

Allows a one–way data binding that sets the content of the editor. Unlike [v-model](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--v-model), the value will not be updated when the content of the editor changes.

```
<template>
    <ckeditor :editor="ClassicEditor" :model-value="data" />
</template>

<script setup>
import { ref } from 'vue';
import { ClassicEditor } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

const data = ref( '<p>Hello world!</p>' );
</script>

```

To execute an action when the editor data changes, use the [input](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--input) event.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--config">

#### `config`

Specifies the [configuration](../../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) of the editor.

```
<template>
    <ckeditor :editor="ClassicEditor" :config="config" />
</template>

<script setup>
import { computed } from 'vue';
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

const config = computed( () => {
    return {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Essentials, Paragraph, Bold, Italic ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
    };
} );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--disabled">

#### `disabled`

This directive controls the [isReadOnly](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property of the editor.

It sets the initial read–only state of the editor and changes it during its lifecycle.

```
<template>
    <ckeditor :editor="ClassicEditor" :disabled="disabled" />
</template>

<script setup>
import { ref } from 'vue';
import { ClassicEditor } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

const disabled = ref( true );
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--disabletwowaydatabinding">

#### `disableTwoWayDataBinding`

Allows disabling the two-way data binding mechanism. The default value is `false`.

The reason for introducing this option is performance issues in large documents. After enabling this flag, the `v-model` directive will no longer update the connected value whenever the editor’s data is changed.

This option allows the integrator to disable the default behavior and only call the [editor.getData()](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method on demand, which prevents the slowdowns. You can read more in the [relevant issue](https://github.com/ckeditor/ckeditor5-vue/issues/246).

```
<ckeditor :editor="editor" :disableTwoWayDataBinding="true" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--component-events">

### Component events

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--ready">

#### `ready`

Corresponds to the [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready) editor event.

```
<ckeditor :editor="editor" @ready="onEditorReady" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--focus">

#### `focus`

Corresponds to the [focus](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-focus) editor event.

```
<ckeditor :editor="editor" @focus="onEditorFocus" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--blur">

#### `blur`

Corresponds to the [blur](../../../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#event-blur) editor event.

```
<ckeditor :editor="editor" @blur="onEditorBlur" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--input">

#### `input`

Corresponds to the [change:data](../../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#event-change:data) editor event.

```
<ckeditor :editor="editor" @input="onEditorInput" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--destroy">

#### `destroy`

Corresponds to the [destroy](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-destroy) editor event.

**Note:** Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.

```
<ckeditor :editor="editor" @destroy="onEditorDestroy" />

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--how-to">

### How to?

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--using-the-document-editor-type">

#### Using the Document editor type

If you use the [Document (decoupled) editor](#ckeditor5/latest/framework/deep-dive/ui/document-editor.html) in your application, you need to [manually add the editor toolbar to the DOM](../../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create).

Since accessing the editor toolbar is not possible until after the editor instance is [ready](../../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#event-ready), put your toolbar insertion code in a method executed upon the [ready](#ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--ready) event of the component, like in the following example:

```
<template>
    <ckeditor :editor="DecoupledEditor" @ready="onReady" />
</template>

<script setup>
import { DecoupledEditor } from 'ckeditor5';
import { Ckeditor } from '@ckeditor/ckeditor5-vue';

import 'ckeditor5/ckeditor5.css';

function onReady( editor )  {
    // Insert the toolbar before the editable area.
    editor.ui.getEditableElement().parentElement.insertBefore(
        editor.ui.view.toolbar.element,
        editor.ui.getEditableElement()
    );
}
</script>

```

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--using-the-editor-with-collaboration-plugins">

#### Using the editor with collaboration plugins

We provide a **ready-to-use integration** featuring collaborative editing in a Vue application:

* [CKEditor 5 with real-time collaboration features and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/real-time-collaboration-for-vue)
* [CKEditor 5 with offline comments, track changes and revision history features](https://github.com/ckeditor/ckeditor5-collaboration-samples/tree/master/collaboration-for-vue)

It is not mandatory to build applications on top of the above sample, however, it should help you get started.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--localization">

#### Localization

CKEditor 5 supports [multiple UI languages](#ckeditor5/latest/getting-started/setup/ui-language.html), and so does the official Vue component. Follow the instructions below to translate CKEditor 5 in your Vue application.

Similarly to CSS style sheets, both packages have separate translations. Import them as shown in the example below. Then, pass them to the `translations` array inside the `config` prop in the component:

```

<script setup>
import { computed } from 'vue';
import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';

const config = computed( () => {
    return {
        translations: [ coreTranslations, premiumFeaturesTranslations ],
        // Other configuration options
    };
} );
</script>

```

For more information, refer to the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--jest-testing">

#### Jest testing

You can use Jest as a test runner in Vue apps. Unfortunately, Jest does not use a real browser. Instead, it runs tests in Node.js that uses JSDOM. JSDOM is not a complete DOM implementation, and while it is sufficient for standard apps, it cannot polyfill all the DOM APIs that CKEditor 5 requires.

For testing CKEditor 5, it is recommended to use testing frameworks that utilize a real browser and provide a complete DOM implementation. Some popular options include:

* [Vitest](https://vitest.dev/)
* [Playwright](https://playwright.dev/)
* [Cypress](https://www.cypress.io/)

These frameworks offer better support for testing CKEditor 5 and provide a more accurate representation of how the editor behaves in a real browser environment.

If this is not possible and you still want to use Jest, you can mock some of the required APIs. Below is an example of how to mock some of the APIs used by CKEditor 5:

```
import { TextEncoder } from 'util';

beforeAll( () => {
    window.TextEncoder = TextEncoder;

    window.scrollTo = jest.fn();

    window.ResizeObserver = class ResizeObserver {
        observe() {}
        unobserve() {}
        disconnect() {}
    };

    for (const key of ['InputEvent', 'KeyboardEvent']) {
        window[key].prototype.getTargetRanges = () => {
            const range = new StaticRange({
                startContainer: document.body.querySelector('.ck-editor__editable p')!,
                startOffset: 0,
                endContainer: document.body.querySelector('.ck-editor__editable p')!,
                endOffset: 0,
            });

            return [range];
        };
    }

    const getClientRects = () => ({
        item: () => null,
        length: 0,
        [Symbol.iterator]: function* () {}
    });

    Range.prototype.getClientRects = getClientRects;
    Element.prototype.getClientRects = getClientRects;

    if ( !Document.prototype.createElementNS ) {
        Document.prototype.createElementNS = ( namespace, name ) => {
            const element = document.createElement( name );
            element.namespaceURI = namespace;
            return element;
        };
    }
} );

```

These mocks should be placed before the tests that use CKEditor 5\. They are imperfect and may not cover all the cases, but they should be sufficient for basic initialization and rendering editor. Remember that they are not a replacement for proper browser testing.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--contributing-and-reporting-issues">

### Contributing and reporting issues

The source code of this component is available on GitHub in <https://github.com/ckeditor/ckeditor5-vue>.

<a id="ckeditor5/latest/getting-started/installation/self-hosted/vuejs-v3.html--next-steps">

### Next steps

* See how to manipulate the editor’s data in the [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) guide.
* Refer to further guides in the [setup section](#ckeditor5/latest/getting-started/setup/configuration.html) to see how to customize your editor further.
* Check the [features category](#ckeditor5/latest/features/index.html) to learn more about individual features.

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html">source file: "ckeditor5/latest/getting-started/licensing/license-and-legal.html"</a>

## Editor license and legal terms

CKEditor is dual-licensed. This means you can choose between an open-source and a commercial license.

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--open-source-license">

### Open source license

The open-source distribution of CKEditor 5 is licensed under the terms of GPL 2+. If you are running an open-source project with an OSS license incompatible with GPL please [contact us](https://ckeditor.com/contact/) – we will be happy to support your project with a [CKEditor 5 open-source license that works for you](https://ckeditor.com/wysiwyg-editor-open-source/).

The following features are available for the GPL-compliant projects, but their availability varies depending on the commercial licensing plans:

* [Page break](#ckeditor5/latest/features/page-break.html)
* [Remove format](#ckeditor5/latest/features/remove-format.html)
* [Special characters](#ckeditor5/latest/features/special-characters.html)
* [Layout tables](#ckeditor5/latest/features/tables/layout-tables.html)
* [Column resize](#ckeditor5/latest/features/tables/tables-resize.html)
* [Image Resize](#ckeditor5/latest/features/images/images-resizing.html)
* [Simple Upload Adapter](#ckeditor5/latest/features/images/image-upload/simple-upload-adapter.html)
* [Base64 adapter](#ckeditor5/latest/features/images/image-upload/base64-upload-adapter.html)
* [HTML embed](#ckeditor5/latest/features/html/html-embed.html)
* [Restricted editing](#ckeditor5/latest/features/restricted-editing.html)
* [Paste From Office](#ckeditor5/latest/features/pasting/paste-from-office.html)
* [Word count](#ckeditor5/latest/features/word-count.html)
* [Find and replace](#ckeditor5/latest/features/find-and-replace.html)
* [Bookmarks](#ckeditor5/latest/features/bookmarks.html)
* [Full page HTML](#ckeditor5/latest/features/html/full-page-html.html)
* [Table and cell properties](#ckeditor5/latest/features/tables/tables-styling.html)
* [List properties](#ckeditor5/latest/features/lists/lists-properties.html)
* [Multi-root editor](#ckeditor5/latest/getting-started/setup/editor-types.html--multi-root-editor)

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--commercial-license">

### Commercial license

The commercial license unlocks many benefits. All commercial plans include:

* No GPL restrictions,
* [White-labeling](#ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html) (except the free plan),
* Technical support (except the free plan).

Additionally, depending on the plan you choose, you gain access to Premium features such as:

* [Asynchronous and Real-Time Collaboration](#ckeditor5/latest/features/collaboration/collaboration.html)
* [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html)
* [Export to Word](#ckeditor5/latest/features/converters/export-word.html)
* [Export to PDF](#ckeditor5/latest/features/converters/export-pdf.html)
* [Multi-level Lists](#ckeditor5/latest/features/lists/multi-level-lists.html)
* [Merge Fields](#ckeditor5/latest/features/merge-fields.html)
* [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)
* [CKBox for file storage and management](#ckeditor5/latest/features/file-management/ckbox.html)
* [Image Optimizer powered by Uploadcare](#ckeditor5/latest/features/file-management/uploadcare.html)

Some premium features are included in selected pricing plans, while others are available as add-ons depending on the selected deployment model and plan.

[Visit the CKEditor 5 Pricing page](https://ckeditor.com/pricing) to find out more or [start the 14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--distribution-options-on-commercial-license">

#### Distribution options on commercial license

CKEditor 5 commercial plans are available with different distribution models:

**Cloud-hosted distribution**

Cloud-hosting is available in self-service and custom plans. The packages are managed and hosted through a CDN, providing quick setup and maintenance-free deployment.

**Self-hosted distribution**

Self-hosted distribution is available with custom plans, allowing you to host CKEditor 5 on your own infrastructure. This option provides greater flexibility and complete control over your deployment environment.

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--ckeditor-5-lts-edition">

### CKEditor 5 LTS Edition

[CKEditor 5 LTS Edition](https://ckeditor.com/ckeditor-5-lts/) provides an extended support cycle of up to three years with security updates and critical compatibility fixes, without introducing breaking changes. It is available entirely under commercial terms and follows the same licensing model as our commercially licensed functionalities.

While the source code of the LTS-only distribution (meaning the versions available only to LTS Edition customers) will continue to be published in our public repositories, the LTS-only distribution cannot be used under GPL.  
To learn more about using the LTS Edition, please visit the [dedicated guide](#ckeditor5/latest/getting-started/setup/using-lts-edition.html) in our documentation or [contact our sales team](https://ckeditor.com/contact-sales/) for details.

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--sources-of-intellectual-property-included-in-ckeditor">

### Sources of intellectual property included in CKEditor

Where not otherwise indicated, all CKEditor 5 content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.

<a id="ckeditor5/latest/getting-started/licensing/license-and-legal.html--trademarks">

### Trademarks

CKEditor is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com/) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html">source file: "ckeditor5/latest/getting-started/licensing/license-key-and-activation.html"</a>

## License key and activation

This article explains how to obtain a commercial license for CKEditor 5 and the CKEditor premium features.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--obtaining-a-license">

### Obtaining a license

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--free-commercial-plan">

#### Free commercial plan

CKEditor 5 offers a [free commercial plan](https://portal.ckeditor.com/checkout?plan=free) with cloud distribution via CDN. This plan includes up to 1,000 editor loads per month and provides access to a limited set of features. It is designed for small-scale projects that need commercial licensing but don’t require the full range of premium features or self-hosted deployment.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--purchasing-a-commercial-license">

#### Purchasing a commercial license

If you wish to purchase a commercial CKEditor 5 license there are two options to do that.

1. Use our [pricing page](https://ckeditor.com/pricing/). You can choose from predefined plans that will allow you to use the editor with our Cloud CDN.
2. [Contact our sales team](https://ckeditor.com/contact/) if you have some specific needs, and you want to use the self-hosted editor.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--choosing-a-distribution-method">

#### Choosing a distribution method

When you choose the editor license you need to decide how the editor will be distributed, via cloud or self-hosted. Key differences are:

* **Cloud-hosted**: Served via our CDN, globally distributed access, no hosting setup required. Subject to [usage-based billing](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html).
* **Self-hosted**: Setup with npm or ZIP download, offers more flexibility in hosting. This type requires contact with our sales team and a custom plan.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--subscribing-to-the-ckeditor-premium-features-free-trial">

#### Subscribing to the CKEditor Premium Features free trial

If you wish to test our offer, you can create an account by [signing up for CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free). After signing up, you will receive access to the Customer Portal.

The trial is commitment-free, and you do not need to provide credit card details to start it. The Premium Features free trial allows you to test all paid features and products at no cost.

Trial allows testing both self-hosted and cloud distributions. When the trial finishes, you have to use the distribution according to your plan details.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--using-the-gpl-key">

#### Using the GPL key

CKEditor 5 can be used in an open-source, GPL-compliant setup with:

* legacy GPL accounts in our Customer Portal. Use the `'GPL'` value in the `licenseKey` field in your configuration.
* without account setup as open-source software under the GPL. Use the `'GPL'` value in the `licenseKey` field in your configuration.

In both cases, the editor will [display a small “Powered by CKEditor” logo](#ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html) in the editor area.

If you are running an Open Source project under an OSS license incompatible with GPL, please [contact us](https://ckeditor.com/contact/). We will be happy to [support your project with a free CKEditor 5 license](https://ckeditor.com/wysiwyg-editor-open-source/).

For commercial purposes, [trial, development, and production license keys](#ckeditor5/latest/getting-started/licensing/license-and-legal.html) are available.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-set-up">

### License key set up

Follow this guide to get the license key necessary to create an account and use premium features.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--create-an-account">

#### Create an account

Create an account either by:

1. [Signing up for the CKEditor Free plan](https://portal.ckeditor.com/checkout?plan=free).
2. Or by choosing [a specific paid plan](https://ckeditor.com/pricing) according to your needs.

Both options are granted a 14-day trial to test all premium features.

After signing up, you will receive access to the Customer Portal.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--log-in-to-the-customer-portal">

#### Log in to the Customer Portal

Log in to the [Customer Portal](https://portal.ckeditor.com/). During the first login, you will receive a confirmation email with a link to create a password for your account.

Keep the password safe, as this trial account will be converted into a commercial account if you decide to buy the license after the trial period is over.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--access-the-portal">

#### Access the portal

Once logged in, you will have access to all the products available. Please note, that there are two types of premium features: standalone plugins and services. You can access the license keys via the “License keys” and “Cloud environments” sections, respectively.

The “License keys” section provides authorization for standalone features. You can copy the desired key and paste it in your editor configuration, [as shown further in this guide](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--using-the-license-key).

For services such as document converters, you will need different kinds of authorization. For details on how to apply those credentials, please refer to respective feature guides. Or find out installation details available in the [Cloud Services section](#cs/latest/guides/overview.html) of the documentation.

To use the access credentials for services, you first need to choose the environment. You may need to create one if there is none.

A token URL and other authentication methods will be assigned to this specific environment. This way you can use separate instances of the editor.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types">

### License key types

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--trial-license-key">

#### Trial license key

This key grants access to **all features.** It is valid for **14 days.** It is perfect for evaluating the platform and all its features. The key exists only for evaluation purposes.

* **Features**: Grants access to all features and add-ons.
* **Duration**: Valid for 14 days.
* **Functionality**: The editor has limited functionality regarding session time and the number of changes allowed.
* **Intended use**: Ideal for evaluating the platform and all its features.
* **Usage limitation**: Can only be used for evaluation purposes and not for production.
* **Editor loads**: It does not consume editor loads, regardless of the plan type.

You can sign up for the [CKEditor Premium Features 14-day free trial](https://portal.ckeditor.com/checkout?plan=free) to test the editor.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--development-license-key">

#### Development license key

This key grants access to your subscription features. It does not consume editor loads, but editor is limited functionally (for example session time, number of changes, development domains). It is **perfect for development environments** (local work, CI, E2E tests). It must not be used for production environments.

* **Features**: Grants access to subscription features.
* **Functionality**:  
  * Limitations on development domains apply on usage-based plans. The editor can be used in the following domains: `localhost`, `*.test`, `*.localhost`, `*.local`, and IP addresses: `127.0.0.1`, `192.168.*.*`, `10.*.*.*`, `172.*.*.*`.
  * The editor will show a banner informing it was launched for development purposes.
* **Intended use**: Designed for development environments such as local work, continuous integration (CI), and end-to-end (E2E) tests.
* **Usage limitation**: Must not be used for production environments.
* **Editor loads**: It does not consume editor loads, regardless of the plan type.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--production-license-key">

#### Production license key

This key grants access to your subscription features without imposing any operational limitations.

* **Features**: Grants access to subscription features.
* **Functionality**: The editor functions without any restrictions.
* **Intended use**: Meant for production environments where the software is actively used by end-users.
* **Usage limitation**: None specified.
* **Editor loads**: Depending on your plan type:  
  * It consumes editor loads if you are on our usage-based billing plans.
  * It does not consume editor loads if you are not on a plan with usage-based billing.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--evaluation-license-key">

#### Evaluation license key

This license key is a temporary, evaluation-only key generated by our team to support short-term testing and demonstration purposes. It is intended for use in events, sample code, or brief evaluations, allowing limited access to essential platform features.

* **Features**: Grants access to open-source features only.
* **Duration**: Typically valid for 24 hours to accommodate short-term needs.
* **Functionality**: The editor is limited functionally, such as session time and the number of changes allowed.
* **Intended use**: Ideal for quick evaluations, demos, or inclusion in code samples.
* **Usage limitation**: Issued solely for evaluation purposes by our team; not authorized for production use.
* **Editor loads**: This license does not consume editor loads, ensuring it is lightweight for temporary testing.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--using-the-license-key">

### Using the license key

You need to add the license key to your CKEditor 5 configuration. It is enough to add the license key once for the standalone features listed in this guide, no matter which and how many premium features you intend to use. Refer to respective feature guides to learn how to configure services, such as document converters and CKBox.

```
ClassicEditor
    .create( {
        // Provide the licence key.
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.

        // Load the plugins.
        plugins: [ /* ... */ ],

        // Display the feature UI element in the toolbar.
        toolbar: [ /* ... */ ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

To use premium features, you need to add the relevant plugins to your CKEditor 5\. You can use the [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) to generate a CKEditor 5 preset with the plugins enabled.

Alternatively, refer to the installation sections in the plugin documentation to do it on your own. You can read more about [installing plugins](#ckeditor5/latest/getting-started/setup/configuration.html) and [toolbar configuration](#ckeditor5/latest/getting-started/setup/toolbar.html) in dedicated guides.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--approved-hosts-whitelisting">

### Approved hosts whitelisting

The Customer Portal provides an optional approved hosts whitelisting feature for production license keys. This feature allows you to restrict the editor’s usage to specific domains or IP addresses. This security enhancement prevents unauthorized use of your license key.

* **Default behavior**: This is an opt-in feature – by default, production license keys have no domain restrictions.
* **Configuration**: You can specify up to 5 domains or IP addresses for which the license key can be used.

To set it up:

1. [Sign in to the Customer Portal](https://portal.ckeditor.com/).
2. Visit the _License keys_ tab.
3. Click _Manage_ action for your production key.
1. Add up to five approved domains. Available patterns:  
  * Domain or IP address: specify exact domains (for example: `example.com`) or IP addresses (`192.168.0.0`).
  * Wildcard in domain: use `*` for subdomains (`*.example.com` allows `api.example.com` and `www.example.com`).
  * Wildcard in IP address: use `*` for segments (`192.168.*.*` allows `192.168.0.0` to `192.168.255.255`).
1. Save the changes.
2. Replace the license key in your editor with the new one created so that it starts working.

<a id="ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-recreation">

### License key recreation

New license keys may be created in your account. Recreation may happen under the following circumstances:

* **Upon request**: You can request a license key creation.
* **Feature updates**: New keys will be created if new features are added to your subscription, either through a plan upgrade or additions to your current plan.
* **Approved host whitelisting**: When you create or update the approved hosts list, a new key will be created.

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html">source file: "ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html"</a>

## Whitelabelling CKEditor 5

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--why-the-powered-by-ckeditor-logo">

### Why the “Powered by CKEditor” logo?

Starting from version [v38.0.0](https://github.com/ckeditor/ckeditor5/releases/tag/v38.0.0), all **open-source** installations of CKEditor 5 display a small “Powered by CKEditor” logo in the bottom-right corner of the editing area. The label links directly to the [CKEditor website](https://ckeditor.com/). The new branding approach is designed to make sure the entire community knows who is powering and modernizing their rich text editor.

This logo is only visible when the editor is focused and only in the editable. The editor needs to have a minimum size of 350px x 50px to display the logo. It will be shown in all editor types. You can observe this behavior in practice in the demo editors further in this guide.

The logo **will not be displayed for customers with commercial licenses**, but please read on as certain actions need to be taken to white-label your CKEditor 5 installation. You can [reach out to our Technical Support team](https://ckeditor.com/contact/) if you have any questions.

However, even as a paid customer, you can [keep the logo](#ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--how-to-keep-the-powered-by-ckeditor-logo) if you wish.

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--how-to-remove-the-powered-by-ckeditor-logo">

### How to remove the “Powered by CKEditor” logo?

To remove the logo, you can obtain a commercial license and then configure the [config.licenseKey](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-licenseKey) setting.

Refer to the [License key and activation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) guide for details on where to find the license key and how to use it in your configuration.

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--how-to-keep-the-powered-by-ckeditor-logo">

### How to keep the “Powered by CKEditor” logo?

If you wish to keep the “Powered by CKEditor” logo in your editor even if you are a paid customer (numerous reasons can play a factor here), you can do it easily. Just set the following option to `true` (by default it is set to `false`) and enjoy the branding!

```
config.ui.poweredBy.forceVisible: true

```

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--how-to-configure-the-layout-of-the-powered-by-ckeditor-logo">

### How to configure the layout of the “Powered by CKEditor” logo?

For free, open-source users, the “Powered by CKEditor” logo will always be displayed when the editor is in focus. You can, however, adjust some aspects of it to suit your editor integration better.

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--layout-customization">

#### Layout customization

You can configure the following properties of the logo:

* The **position** relative to the editor’s bottom edge. The default is over the edge. The logo can also be displayed inside the container.
* The logo **offset** relative to the configured editable element’s corner.
* The **alignment**: left or right side of the editable area.
* The **label** text, displayed before the CKEditor logo.

The complete reference is available in the [API documentation](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-ui).

The example below shows how the logo can be adjusted using the available editor configuration. Focus the editor to display the customized logo.

And this is the configuration code necessary:

```
ClassicEditor
    .create( {
        /* ... */
        ui: {
            poweredBy: {
                position: 'inside',
                side: 'left',
                label: 'This is'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/getting-started/licensing/managing-ckeditor-logo.html--styling-customization">

#### Styling customization

A set of ready-made CSS variables is available for integrators. You can use it to customize the style of the “Powered by CKEditor” logo.

```
/*
 * Default values.
 */
:root {
    --ck-powered-by-line-height: 10px;
    --ck-powered-by-padding-vertical: 2px;
    --ck-powered-by-padding-horizontal: 4px;
    --ck-powered-by-text-color: hsl(0, 0%, 31%);
    --ck-powered-by-border-radius: 100px;
    --ck-powered-by-background: hsl(0, 0%, 100%);
    --ck-powered-by-border-color: var(--ck-color-focus-border);
}

```

If you need, you can dive even deeper to make it coherent with your product. For instance, this is how the logo can be modified to fit the “dark mode” theme.

It was achieved with just a few style rules:

```
    /* "Powered by CKEditor" logo customization. */
    .ck.ck-balloon-panel.ck-powered-by-balloon {
        /* You can use your own variables here as well. */
        --ck-powered-by-background: hsl(270, 1%, 29%);
        --ck-powered-by-border-color: hsl(270, 1%, 29%);
    }

    .ck.ck-balloon-panel.ck-powered-by-balloon .ck.ck-powered-by .ck-powered-by__label {
        text-transform: none;
        font-family: var(--main-font-family);
        padding-left: 2px;
        color: var(--main-text-color);
    }

    .ck.ck-balloon-panel.ck-powered-by-balloon .ck.ck-powered-by .ck-icon {
        filter: brightness(10);
    }

```

Refer to the [Theme customization](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) guide to learn how to adjust the editor theme.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html">source file: "ckeditor5/latest/getting-started/licensing/usage-based-billing.html"</a>

## Usage-based billing

Under the Usage-based billing (UBB) model, your costs are based on how frequently you use CKEditor.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--key-terms">

### Key terms

Familiarizing yourself with these key terms related to usage-based billing will help you choose the right pricing plan for your needs:

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--cloud-hosted">

#### Cloud-hosted

A reliable cloud-based CDN service that hosts CKEditor 5, ensuring it is globally distributed and always close to your users for optimal performance. By choosing this deployment method, you leverage our infrastructure, eliminating the need to manage hosting yourself.

Additionally, you gain access to both standard and premium features, with the added benefit of quick updates, so your CKEditor is always equipped with the latest enhancements, security patches, and new features with little effort on your part.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--self-hosted">

#### Self-hosted

Distribute CKEditor from your own servers using npm packages or ZIP files. This method offers the most flexibility, allowing you to bundle and configure the editor to suit your specific needs. If you plan to use the editor commercially in a self-hosted environment, please [contact our sales team](https://ckeditor.com/contact-sales/#contact-form).

Alternatively, if you prefer to use only the free, open-source version of CKEditor and your project complies with our open-source software license, you can choose to self-host CKEditor on your servers or through any CDN service, without relying on our Cloud services.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--editor-loads">

#### Editor loads

An editor load occurs each time CKEditor is initialized in your application. For example, if 100 users load CKEditor 10 times each, it results in 1,000 editor loads.

The editor initializes as follows:

1. The integrator creates one or more editors on a page, typically using a method like `ClassicEditor.create(configuration)`.
2. Depending on the setup, the editor will either initialize with the selected DOM element or, if provided with data, initialize in a detached mode to be added to the DOM on demand.
3. Upon the `ready` event, the editor sends usage information to the server to confirm the license. [Read more about the license check](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--license-check-and-usage-data).

Each individual editor instance on a page is counted as one editor load. For example, if a page contains ten editors, a single refresh of that page will result in ten editor loads.

Several factors can contribute to a high number of editor loads, with one of the most significant being the use of multiple editors on a single page. For example:

* **Content Management Systems (CMS)**: CMS platforms where users frequently edit content across multiple fields (such as title, description, body content) on the same page can lead to a higher count of editor loads.
* **Dynamic form builders**: Applications that allow users to dynamically add and edit form fields with CKEditor embedded in each field will increase the total number of editor loads each time the form is accessed or modified.

By understanding these scenarios, you can better anticipate and manage your editor loads to align with your usage plan.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--license-check-and-usage-data">

#### License check and usage data

When the editor is ready, a license check request is sent to our server, along with non-personalized data that helps us understand editor usage. This information also assists us when we work on support requests.

The server’s response confirms whether the license is valid. If invalid, the editor will switch to read-only mode.

**Note:** Remember to set correct [Content Security Policy (CSP)](#ckeditor5/latest/getting-started/setup/csp.html) rules to enable usage metering.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--how-usage-based-billing-works">

### How usage-based billing works

Each pricing plan includes a specific number of editor loads. If you exceed this limit, you can either upgrade to a higher plan or pay for additional editor loads in blocks of 1,000.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--billing-and-metering-cycles">

#### Billing and metering cycles

Your billing cycle depends on the type of subscription plan you have chosen – **monthly** or **annual**.

* **Monthly Plans**: If you are on a monthly plan, your billing cycle begins the day after your trial period ends and repeats on the same date each month. For example, if your trial ends on May 15th, your billing cycle starts on May 16th. Your editor load count resets on the 16th of each following month. Any charges for additional editor loads take effect at the start of your next billing cycle.
* **Annual Plans**: If you have chosen an annual plan, your billing cycle starts the day after your trial period ends and continues for 12 months. Editor loads are still calculated and reset on a monthly basis within your annual billing period. For instance, if your trial ends on May 15th, your billing cycle begins on May 16th, and your editor load count resets on the 16th of each month thereafter. If you exceed your monthly editor load limit, additional charges of the standard charging rate per block of 1,000 editor loads will apply. These charges will be conducted monthly if applicable.

Please note that unused editor loads **do not carry over** to the next month, regardless of whether you are on a monthly or annual plan. To manage your costs effectively, we recommend monitoring your editor load usage and adjusting your plan as needed. See the [Managing your usage](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--managing-your-usage) section below.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--exceeding-your-monthly-limit">

#### Exceeding your monthly limit

If you surpass your monthly limit, you will be automatically charged a standard charging rate for every additional block of 1,000 editor loads.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--ckeditor-free-plan">

#### CKEditor Free plan

If you use our [CKEditor Free plan](https://portal.ckeditor.com/checkout?plan=free) and exceed your allocated editor loads without providing a valid payment method, your editor will switch to read-only mode until the next month. If a valid payment method is provided, a standard charge of standard charging rate per additional block of 1,000 editor loads applies.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--trial-period-usage">

#### Trial period usage

During [your 14-day trial](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types), you have unlimited editor loads and can test both distribution methods: cloud and self-hosted. However, once the trial ends, you must use the method included in your selected plan. For instance, if you tested npm (self-hosted) but are on a cloud plan, you will need to either [migrate your implementation to use cloud](#ckeditor5/latest/updating/index.html--migration-to-cdn) or [contact our sales team](https://ckeditor.com/contact/) to switch to a self-hosted plan.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--managing-your-usage">

#### Managing your usage

Admins can monitor usage data from the past six months within the CKEditor Usage section of the Customer Portal. Current cycle data is available in the `Customer Portal` → `Subscription` → `Usage statistics`. We recommend keeping an eye on your editor loads and selecting a plan that fits your usage needs while minimizing costs. You will also receive an email notification when you reach 50% and 70% of your monthly editor loads.

If your usage regularly exceeds your plan’s limit, we recommend upgrading your plan to avoid additional charges. You can view and upgrade your plan at any time via the Customer Portal.

We advise linking the email address associated with your plan to a group alias, IT, or administrative address (for example, `subscriptions@example.com`) to avoid potential disruptions in case of staff or organizational changes.

<a id="ckeditor5/latest/getting-started/licensing/usage-based-billing.html--plan-upgrades">

#### Plan upgrades

If you are on the Essential plan and reach 5,000 editor loads, you will not be automatically upgraded to the Professional plan. Instead, you will be charged a standard charging rate for each additional block of 1,000 editor loads. To avoid these charges, regularly review your editor load count and consider upgrading your plan if needed. Plan upgrades are available anytime in the `Customer Portal` → `Subscription management`.

For plan upgrades, we charge prorated value immediately to enable all needed features after the upgrade.

<a id="ckeditor5/latest/getting-started/setup/configuration.html">source file: "ckeditor5/latest/getting-started/setup/configuration.html"</a>

## Configuring CKEditor 5 features

The functionality of CKEditor 5 is provided by specialized features, accessible via a configurable toolbar or keyboard shortcuts. Some of these features are only available with certain [editor types](#ckeditor5/latest/getting-started/setup/editor-types.html).

<a id="ckeditor5/latest/getting-started/setup/configuration.html--adding-features">

### Adding features

All the [features of CKEditor 5](#ckeditor5/latest/features/index.html) are implemented by plugins. You add plugins by importing them from the main CKEditor 5 package, named `ckeditor5`.

Listed below is an example configuration adding the [block indentation](#ckeditor5/latest/features/indent.html) feature.

Note that some features may require more than one plugin to run, as shown above. This granular approach lets the integrators adjust available features to their specific needs. It is done during the setup and [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) is the easiest way to choose all needed features.

<a id="ckeditor5/latest/getting-started/setup/configuration.html--adding-premium-features">

#### Adding premium features

CKEditor 5 premium features are imported in the same way. However, they have their own package, named `ckeditor5-premium-features`, to import from. These also [require a license](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html). Please see an example below, adding the PDF export feature and configuring it.

<a id="ckeditor5/latest/getting-started/setup/configuration.html--configuring-editor-settings">

### Configuring editor settings

When integrating an editor into your application, you can customize its features by passing a JavaScript object with configuration options to the [create()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create) method. These settings, defined in the [EditorConfig](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create), allow for extensive customization of the editor’s functionality. Remember that customization depends on the editor setup and plugins loaded. The sample snippet below shows the configuration of the toolbar, the headings feature, font family, and color picker settings:

See [EditorConfig](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html) to learn about all available configuration options. Also, check out individual [feature guides](#ckeditor5/latest/features/index.html), listing various configuration options available per feature.

<a id="ckeditor5/latest/getting-started/setup/configuration.html--why-does-the-editor-filter-out-content-such-as-styles-classes-or-html-elements">

#### Why does the editor filter out content such as styles, classes or HTML elements?

CKEditor 5 implements a custom [data model](#ckeditor5/latest/framework/architecture/editing-engine.html). This means that the editor needs to convert every piece of loaded content to that model and then render it back to the view.

Each kind of content must be handled by a plugin. For example, the [ckeditor5-basic-styles](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles) package handles HTML elements such as `<b>`, `<i>`, `<u>`, etc. along with their representation in the model. The feature defines the two–way conversion between the HTML (view) and the editor model.

If you try to load some content unknown to the editor – without a feature loaded to handle it – the editor will drop it.

If you want the editor to handle the HTML5 elements not covered by available feature plugins, you need to write plugins to support them. You can also use the [General HTML Support (GHS)](#ckeditor5/latest/features/html/general-html-support.html) feature. Once you do that, CKEditor 5 will not filter anything out. However, GHS needs to be carefully and precisely configured to ensure stability and security of the implementation.

<a id="ckeditor5/latest/getting-started/setup/configuration.html--removing-features">

### Removing features

In some cases, you may want to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in the editor at runtime.

In the example below, the `Heading` plugin is removed:

You might want to delete the `Link` plugin also, as shown below:

However, this will result in an error thrown in the console of the browser:

```
CKEditorError: plugincollection-required {"plugin":"Link","requiredBy":"Autolink"}
Read more: https://ckeditor.com/docs/ckeditor5/latest/support/error-codes.html#error-plugincollection-required

```

This is a good time to remind you that some plugins in CKEditor 5 depend on each other. In this case, the `Autolink` plugin requires the `Link` plugin to work. To make the above snippet work, the `Autolink` plugin must also be removed:

<a id="ckeditor5/latest/getting-started/setup/csp.html">source file: "ckeditor5/latest/getting-started/setup/csp.html"</a>

## Content Security Policy

CKEditor 5 is compatible with applications that use [CSP rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) and helps developers build a secure web.

<a id="ckeditor5/latest/getting-started/setup/csp.html--recommended-csp-configuration-for-cloud-deployments">

### Recommended CSP configuration for Cloud deployments

The recommended CSP configuration for [Cloud deployments](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--cloud-hosted) that allows the rich-text editor to run out–of–the–box with all standard features using the content like images or media from external hosts looks as follows:

```
default-src 'none'; connect-src 'self'; script-src 'self' https://cdn.ckeditor.com https://proxy-event.ckeditor.com ; img-src * data:; style-src 'self' 'unsafe-inline'; frame-src *

```

<a id="ckeditor5/latest/getting-started/setup/csp.html--recommended-csp-configuration-for-self-hosted-deployments">

### Recommended CSP configuration for self-hosted deployments

The recommended CSP configuration for self-hosted deployments (npm/ZIP) that allows the rich-text editor to run out–of–the–box with all standard features using the content like images or media from external hosts looks as follows:

```
default-src 'none'; connect-src 'self'; script-src 'self'; img-src * data:; style-src 'self' 'unsafe-inline'; frame-src *

```

<a id="ckeditor5/latest/getting-started/setup/csp.html--impact-of-csp-on-editor-features">

### Impact of CSP on editor features

Some CSP directives have an impact on certain rich-text editor features. Here is the round-up of directives and their specific roles in the editor:

* `default-src 'none'`: Resets the policy and blocks everything. All successive directives work as a whitelist. By itself, as long as it is followed by other directives, it has no impact on the editor.
* `connect-src 'self'`

  * Allows the [editor upload features](#ckeditor5/latest/features/images/image-upload/image-upload.html) to use [XMLHttpReqests](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) (Ajax) to upload files to the server, for instance, when an image is pasted or dropped into the editor content. The `'self`’ value ensures the requests remain within the same host.
  * Allows [auto–saving editor data](#ckeditor5/latest/features/autosave.html) using `XMLHttpRequest`.

**Note**: To use [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services/), include the `http://*.cke-cs.com` domain in the `connect-src` directive, for instance: `connect-src 'self' http://*.cke-cs.com`.
* `script-src 'self'`: Allows the execution of JavaScript from the current host only and can be applied only if the CKEditor 5 script file (`<script src="[ckeditor-build-path]/ckeditor.js"></script>`) is also served from that host.

**Note**: If CKEditor 5 is served from [Cloud](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--cloud-hosted), make sure the value of `script-src` includes the required hosts, one for the CDN, and one for the [license check server](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--license-check-and-usage-data): `script-src 'self' https://cdn.ckeditor.com https://proxy-event.ckeditor.com`.
* `img-src * data:`

  * The `*` directive value allows images in the editor content to come from any hosts.
  * The `data:` value allows:  
    * Pasting [images from the clipboard](#ckeditor5/latest/features/images/image-upload/image-upload.html) and [from MS Office](#ckeditor5/latest/features/pasting/paste-from-office.html) into the editor content. Pasted images are usually represented as Base64–encoded strings (`<img src="data:..." />`) and without `data:` they cannot be displayed and uploaded.
    * Displaying the [media embed](#ckeditor5/latest/features/media-embed.html) feature placeholders for the inserted media.

**Note**: Use the more strict `img-src 'self'` if all images in the editor content are hosted from the same domain and you do **not** want to enable the [media embed](#ckeditor5/latest/features/media-embed.html) and [paste from Word](#ckeditor5/latest/features/pasting/paste-from-office.html) features.
* `style-src 'self' 'unsafe-inline'`:

  * The `self` directive allows to load styles from the site’s own domain. Since v42.0.0, the editor [distributes its stylesheets](#ckeditor5/latest/getting-started/setup/css.html). If you need to load styles from some other domain, add them explicitly: `style-src https://trusted-styles.example.com;`.
  * The directive `unsafe-inline` is required to make the styles of certain features work properly. For instance, you are going to need it if you want to enable such editor features as [font](#ckeditor5/latest/features/font.html) or [text alignment](#ckeditor5/latest/features/text-alignment.html) or any other feature that uses the inline `style="..."` attributes in the content.

**Note**: Inline styles are also required when using [list item marker formatting](#ckeditor5/latest/features/lists/lists-properties.html--list-item-marker-formatting). For example, if you apply font color, size, or family to list markers, the editor uses inline style attributes to render them. Because of this, `unsafe-inline` must be allowed for the styles to display correctly.
* `frame-src *`: Necessary for the [media embed](#ckeditor5/latest/features/media-embed.html) feature to load media with previews (containing `<iframe>`).

**Note**: Use the more strict `frame-src 'self'` if all the media in the edited content come from the same domain as your application.

<a id="ckeditor5/latest/getting-started/setup/csp.html--strictest-working-configuration">

### Strictest working configuration

Knowing the role of each directive, the strictest set of rules that allows CKEditor 5 to run is as follows:

```
default-src 'none'; connect-src 'self'; script-src 'self'; img-src 'self'; style-src 'self'; frame-src 'self'

```

This comes with some trade–offs, though. For example, it requires you to:

* Load images in the content from the same host.
* Load previewable media in the content from the same host.
* Give up certain features that use inline styles like [font](#ckeditor5/latest/features/font.html) or [text alignment](#ckeditor5/latest/features/text-alignment.html).
* Give up pasting images from the clipboard or [from Office](#ckeditor5/latest/features/pasting/paste-from-office.html).

<a id="ckeditor5/latest/getting-started/setup/css.html">source file: "ckeditor5/latest/getting-started/setup/css.html"</a>

## Editor and content styles

We distribute CKEditor 5 with two types of styles:

* Editor styles to style the editor’s user interface.
* Content styles for styling content in the editor.

If you went through our [Quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html), you probably noticed that attaching the styles in JavaScript is pretty standard, and we provide CSS style sheets that have both the editor and content styles combined. There are separate styles for open-source and premium features:

```
import 'ckeditor5/ckeditor5.css';

import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

```

It is as easy in HTML if you decide to use our CDN:

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

```

<a id="ckeditor5/latest/getting-started/setup/css.html--why-do-i-need-content-styles">

### Why do I need content styles?

Some [core editor features](#ckeditor5/latest/features/index.html) bring additional CSS to control the look of the content they produce. One such example is the [image feature](#ckeditor5/latest/features/images/images-overview.html), which requires special content styles to render images and their captions within the content. Another would be the [block quote](#ckeditor5/latest/features/block-quote.html) feature that displays quotes in italics with a subtle border on the side. You can see both of these pictured below.

<a id="ckeditor5/latest/getting-started/setup/css.html--customizing-the-editors-look">

### Customizing the editor’s look

CKEditor 5 comes with a predefined theme. But you can easily adjust the editor’s appearance to match your product’s visual identity or design system. Colors, typography, spacing, borders, and other visual aspects of the editor are defined with CSS variables that you can override in your application.

The example below shows how the customized variables affect the editor’s appearance.

```
:root {
    --ck-color-focus-border: hsl(263, 59%, 52%);
    --ck-color-toolbar-background: hsl(210, 33%, 99%);
    --ck-color-button-on-background: hsl(210, 8%, 95%);
    --ck-color-button-on-color: hsl(263, 59%, 52%);
    --ck-font-size-base: 16px;
    --ck-spacing-unit: 1em;
    --ck-border-radius: 16px;
}

```

The default editor’s look:

The editor’s look after customization:

Here are some essential CSS variables for customizing the editor:

| Variable                                    | Description                                              |
| ------------------------------------------- | -------------------------------------------------------- |
| \--ck-border-radius                         | Border radius for rounded corners throughout the editor. |
| \--ck-spacing-unit                          | Base spacing unit that controls all spacing in the UI.   |
| \--ck-font-size-base                        | Base font size for the editor UI.                        |
| \--ck-font-face                             | Font family used throughout the editor UI.               |
| \--ck-color-focus-border                    | Border color when elements are focused.                  |
| \--ck-color-toolbar-background              | Background color of the toolbar.                         |
| \--ck-color-base-border                     | Primary border color used throughout the UI.             |
| \--ck-color-button-on-background            | Background color for active/selected buttons.            |
| \--ck-color-button-on-color                 | Text color for active/selected buttons.                  |
| \--ck-color-button-default-hover-background | Background color when hovering over buttons.             |

Knowing the variables, you can push the customization even further and create your own themes, as in this [dark theme example](#ckeditor5/latest/examples/framework/theme-customization.html).

<a id="ckeditor5/latest/getting-started/setup/css.html--customizing-the-look-of-the-features">

### Customizing the look of the features

Similarly to the customizable editor look, some features also provide an interface to change their styles via [native CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS%5Fcascading%5Fvariables/Using%5FCSS%5Fcustom%5Fproperties).

<a id="ckeditor5/latest/getting-started/setup/css.html--general-content-styling">

#### General content styling

CKEditor 5 provides CSS variables to standardize font and line height styling across the content. These variables control the default appearance of text the content. You can override them in the following way:

```
:root {
    /* Override the default font family */
    --ck-content-font-family: "Roboto";
    
    /* Override the default font size */
    --ck-content-font-size: 16px;
    
    /* Override the default font color */
    --ck-content-font-color: hsl(225, 5%, 45.00%);

    /* Override the default line height */
    --ck-content-line-height: 2;
}

```

<a id="ckeditor5/latest/getting-started/setup/css.html--feature-specific-styling">

#### Feature-specific styling

Individual features also provide CSS variables for their specific styling needs. For example, if you want to change the color of the mentions’ background and text, you can do the following override:

```
:root {
    --ck-content-color-mention-background: black;
    --ck-content-color-mention-text: white;
}

```

<a id="ckeditor5/latest/getting-started/setup/css.html--styling-the-published-content">

### Styling the published content

Your application is typically divided into two areas. _Content creation_, which hosts the editor and is a writing tool, and _content publishing_, which presents the written content.

It is important to use the content styles on the publishing side of your application. Otherwise, the content will look different in the editor and for your end users.

There are two ways to obtain the content styles:

* From the `npm` packages, in the `dist/ckeditor5-content.css` and `ckeditor5-premium-features-content.css` location.
* From our CDN, `https://cdn.ckeditor.com/ckeditor5/`

Below is an example with placeholder paths showing how to load the `ckeditor5-content.css` (and `ckeditor5-premium-features-content.css`, if needed) file on the publishing side.

```
<link rel="stylesheet" href="path/to/assets/ckeditor5-content.css">

<link rel="stylesheet" href="path/to/assets/ckeditor5-premium-features-content.css">

<link rel="stylesheet" href="path/to/assets/styles.css">

```

The final setup depends on how your application is structured. As mentioned earlier, you can use our CDN, or your JS bundler already creates and serves combined style sheets. Choose the solution that works best for your case.

<a id="ckeditor5/latest/getting-started/setup/css.html--optimizing-the-size-of-style-sheets">

### Optimizing the size of style sheets

The `ckeditor5` package distributes three style sheets:

* `ckeditor5.css` – combined editor and content styles,
* `ckeditor5-content.css` – only content styles,
* `ckeditor5-editor.css` – only editor styles.

The same is true for the `ckeditor5-premium-features` package, but the filenames are different:

* `ckeditor5-premium-features.css` – combined editor and content styles,
* `ckeditor5-premium-features-content.css` – only content styles,
* `ckeditor5-premium-features-editor.css` – only editor styles.

However, these style sheets include styles for **all** editor plugins. If you want to optimize the size of the style sheet, to only include styles for the plugins you use, you can follow the [Optimizing build size](#ckeditor5/latest/getting-started/setup/optimizing-build-size.html--styles) guide.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html">source file: "ckeditor5/latest/getting-started/setup/customizing-icons.html"</a>

## Customizing icons

CKEditor 5 comes with a set of icons that are used in the editor UI. If you are using self-hosted installation method like npm or ZIP, you can customize the icons by overriding the default npm package that contains them.

There are two ways to do this, and both require overriding the `@ckeditor/ckeditor5-icons` package. One way is to create a custom icons package and override the default icons package in your project using a package manager. The other is to use resolve aliases to replace the icons during the build process.

Let’s start with the first method.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--overriding-icons-using-package-manager">

### Overriding icons using package manager

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--prepare-custom-icons-package">

#### Prepare custom icons package

Inside your project, create a new directory outside the rest of the code (usually the `src` folder) for the custom icons package. Create a `package.json` file with the following content inside it:

```
{
    "name": "my-custom-icons",
    "private": true,
    "version": "0.0.1",
    "type": "module",
    "main": "./dist/index.js"
}

```

Open the `node_modules` directory and look for the `@ckeditor/ckeditor5-icons` package. Inside, you will find the `dist/index.js` file. Copy the content of this file.

Now, create a new directory in the custom icons package directory and name it `dist`. Inside it, create an `index.js` file and paste the content you copied from the `@ckeditor/ckeditor5-icons` package. What you should have is a directory structure looking like this:

```
my-custom-icons/
├── dist/
│   └── index.js
└── package.json

```

Now you can modify the JavaScript strings containing SVG icons in the `index.js` file to customize the icons. Remember to keep the same structure and naming conventions as in the original file.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--override-the-icons-package">

#### Override the icons package

Now that you have custom icons package ready, you can override the default `@ckeditor/ckeditor5-icons` package in your project. This step depends on the package manager you are using. Below you will find examples for npm, Yarn Classic, Yarn Berry, and pnpm.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--npm">

##### npm

If you are using npm, you need to add the following items to your `package.json` file:

```
{
    "dependencies": {
        "@ckeditor/ckeditor5-icons": "file:./icons"
    },
    "overrides": {
        "@ckeditor/ckeditor5-icons": "$@ckeditor/ckeditor5-icons"
    }
}

```

Then, run `npm install` to install the custom icons package.

Please note that the value in the `overrides` object starts with a dollar sign (`$`). This is the npm suggestion to use the package from the `dependencies` section.

You can read more about the `overrides` field in the [npm documentation](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#overrides).

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--yarn-classic">

##### Yarn Classic

If you are using Yarn Classic (v1), you need to add the following items to your `package.json` file:

```
{
    "resolutions": {
        "@ckeditor/ckeditor5-icons": "link:./icons"
    }
}

```

Then, run `yarn install` to install the custom icons package.

You can read more about the `resolutions` field in the [Yarn documentation](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/).

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--yarn-berry">

##### Yarn Berry

If you are using Yarn Berry (v2+), you need to add the following items to your `package.json` file:

```
{
    "resolutions": {
        "@ckeditor/ckeditor5-icons": "link:./icons"
    }
}

```

Then, run `yarn install` to install the custom icons package.

You can read more about the `resolutions` field in the [Yarn documentation](https://yarnpkg.com/configuration/manifest#resolutions).

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--pnpm">

##### pnpm

If you are using pnpm, you need to add the following items to your `package.json` file:

```
{
    "pnpm": {
        "overrides": {
            "@ckeditor/ckeditor5-icons": "link:./icons"
        }
    }
}

```

Then, run `pnpm install` to install the custom icons package.

You can read more about the `resolutions` field in the [pnpm documentation](https://pnpm.io/package%5Fjson#pnpmoverrides).

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--override-icons-using-resolve-aliases">

### Override icons using resolve aliases

If you are using a bundler, you can use resolve aliases to replace the default `@ckeditor/ckeditor5-icons` package with your custom icon file. This method is similar to the one described above, but does not require creating a custom package.

This section only shows selected bundlers as examples, but other bundlers support similar functionality out of the box or with first-party plugins.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--prepare-custom-icon-file">

#### Prepare custom icon file

Open the `node_modules` directory and look for the `@ckeditor/ckeditor5-icons` package. Inside you will find the `dist/index.js` file. Make a copy of this file, move it to your project and rename it if necessary. Then remove the `//# sourceMappingURL=index.js.map` comment at the bottom.

You can modify the JavaScript strings containing SVG icons in this file to customize the icons.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--add-resolve-alias">

#### Add resolve alias

Now that you have a custom icon file, you can add a resolve alias to your bundler configuration. This will cause all imports from the `@ckeditor/ckeditor5-icons` package to resolve to your custom icon file.

Follow the instruction below depending on the bundler you are using.

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--vite">

##### Vite

Open the `vite.config.js` file and add the following code:

```
import { resolve } from 'path';

export default {
    resolve: {
        alias: {
            '@ckeditor/ckeditor5-icons/dist/index.js': resolve( import.meta.dirname, './src/icons.js' )
        }
    }
};

```

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--webpack">

##### Webpack

Open the `webpack.config.js` file and add the following code:

```
import { resolve } from 'path';

export default {
    resolve: {
        alias: {
            '@ckeditor/ckeditor5-icons/dist/index.js': resolve( import.meta.dirname, './src/icons.js' )
        }
    }
};

```

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--esbuild">

##### esbuild

Open the esbuild configuration file and add the following code:

```
import { resolve } from 'path';

build( {
    alias: {
        '@ckeditor/ckeditor5-icons/dist/index.js': resolve( import.meta.dirname, './src/icons.js' )
    }
} );

```

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--rollup">

##### Rollup

Rollup does not support aliases by default, so you need to install the first-party `@rollup/plugin-alias` plugin if you do not already have it. Then add the following code to the `rollup.config.js` file:

```
import { resolve } from 'path';
import alias from '@rollup/plugin-alias';

export default {
    plugins: [
        alias( {
            entries: {
                '@ckeditor/ckeditor5-icons/dist/index.js': resolve( import.meta.dirname, './src/icons.js' )
            }
        } )
    ]
};

```

<a id="ckeditor5/latest/getting-started/setup/customizing-icons.html--rolldown">

##### Rolldown

Open the `rolldown.config.js` file and add the following code:

```
import { resolve } from 'path';

export default {
    resolve: {
        alias: {
            '@ckeditor/ckeditor5-icons/dist/index.js': resolve( import.meta.dirname, './src/icons.js' )
        }
    }
};

```

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html">source file: "ckeditor5/latest/getting-started/setup/editor-lifecycle.html"</a>

## Editor lifecycle

Each CKEditor 5 **type** provides a different **editor class** that handles the creation of editor instances. Most of the examples in the documentation use the [ClassicEditor](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html) class, but things should work similarly with other types.

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html--creating-an-editor-with-create">

### Creating an editor with `create()`

Regardless of the chosen type, creating an editor is done using the static `create()` method. Usually, you start with an HTML element that will be a place where an editor will render itself on a page.

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html--example-classic-editor">

#### Example: Classic editor

Add an element that CKEditor 5 should replace on your HTML page:

```
<div id="editor">
    <p>Here goes the initial content of the editor.</p>
</div>

```

Then you call [ClassicEditor.create()](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#static-function-create) to **replace** the `<div>` element with a classic editor:

After creation, the editor will appear on the page in the selected area.

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html--example-decoupled-editor">

#### Example: Decoupled editor

Add the elements where CKEditor 5 should initialize the toolbar and the editable to your page:

```
<!-- The toolbar will be rendered in this container. -->
<div id="toolbar-container"></div>

<!-- This container will become the editable. -->
<div id="editor">
    <p>This is the initial editor content.</p>
</div>

```

Then call the [DecoupledEditor.create()](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html#static-function-create) method to create a decoupled editor instance with the toolbar and the editable in two separate containers:

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html--getting-the-editors-instance">

### Getting the editor’s instance

The simplest way is to save the reference to the editor somewhere after you create it. This is often done by using a window or some state management object. You will often see lines like this in our documentation.

```
// Editor's creation steps.
// ...
.then( editor => {
    window.editor = editor;
})

// Or with the await (if your setup supports it):
const editor = await ClassicEditor.create( /* ... */  );

```

<a id="ckeditor5/latest/getting-started/setup/editor-lifecycle.html--destroying-the-editor-with-destroy">

### Destroying the editor with `destroy()`

In modern applications, it is common to create and remove elements from the page interactively through JavaScript. In such cases, CKEditor 5 instances should be destroyed by using the `destroy()` method:

```
editor
    .destroy()
    .catch( error => {
        console.log( error );
    } );

```

Once the editor is destroyed, resources used by the editor instance are released. However, if `updateSourceElementOnDestroy` is enabled, the original element (`<textarea>` or similar) used to create the editor is updated to reflect the final editor content upon destruction. This has some security implication, so enable it only after making yourself familiar with [this related section](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--updating-the-source-element).

<a id="ckeditor5/latest/getting-started/setup/editor-types.html">source file: "ckeditor5/latest/getting-started/setup/editor-types.html"</a>

## Editor types

The editor’s user interface is dependent on the editor types. The editor provides functionality through specialized features accessible via a configurable toolbar or keyboard shortcuts. Some of these features are only available with certain editor types.

There are six ready-made editor types (see below) available for CKEditor 5\. They offer different functional approaches to editing as well as various UI solutions. Editor types are imported from the main `ckeditor5` package, the same way features are imported, as shown in the [Quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide.

Other custom-tailored editor types can be made using the [CKEditor 5 Framework](#ckeditor5/latest/framework/deep-dive/ui/external-ui.html).

For example, this code will import the classic editor type and some essential text formatting plugins. It also provides the configuration of the [main editor toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html).

<a id="ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor">

### Classic editor

Classic editor is what most users traditionally learned to associate with a rich-text editor – a toolbar with an editing area placed in a specific position on the page, usually as a part of a form that you use to submit some content to the server.

See an [example of the classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in action.

Use the following import to put classic editor on your page:

<a id="ckeditor5/latest/getting-started/setup/editor-types.html--inline-editor">

### Inline editor

The inline editor comes with a floating toolbar that becomes visible when the editor is focused (for example, by clicking it). A common scenario for using the inline editor is offering users the possibility to edit content (such as headings and other small areas) in its real location on a web page instead of doing it in a separate administration section.

See an [example of the inline editor](#ckeditor5/latest/examples/builds/inline-editor.html) in action.

Use the following import to put inline editor on your page:

<a id="ckeditor5/latest/getting-started/setup/editor-types.html--balloon-editor-and-balloon-block-editor">

### Balloon editor and balloon block editor

Balloon editor is similar to inline editor. The difference between them is that the [toolbar appears in a balloon](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar) next to the selection (when the selection is not empty).

See an [example of the balloon editor](#ckeditor5/latest/examples/builds/balloon-editor.html) in action.

Balloon block is essentially the balloon editor with an extra block toolbar, which can be accessed using the button attached to the editable content area and following the selection in the document. The toolbar gives access to additional block–level editing features.

See an [example of the balloon block editor](#ckeditor5/latest/examples/builds/balloon-block-editor.html) in action.

Use one of the following imports to put balloon or balloon block editor on your page:

or

<a id="ckeditor5/latest/getting-started/setup/editor-types.html--decoupled-editor-document">

### Decoupled editor (document)

The Decoupled editor is named for its unique structure, where the toolbar and editing area are separate elements. This design allows for greater flexibility and customization, making it suitable for a wide range of applications beyond just classic WYSIWYG editing.

The most popular use case for the Decoupled editor is the “document editor,” similar to large editing packages such as Google Docs or Microsoft Word. It works best for creating documents, which are usually later printed or exported to PDF files.

By separating the toolbar from the editing area, you can integrate the editor into different parts of your application or customize its appearance and functionality to suit various needs. For example, you may want to create an email creator that reflects the setup in which the toolbar is at the bottom of the editing area. We have [a working example](#ckeditor5/latest/examples/framework/bottom-toolbar-editor.html) for this.

See an [example of the document editor](#ckeditor5/latest/examples/builds/document-editor.html) in action.

Use the following import to put classic editor on your page:

<a id="ckeditor5/latest/getting-started/setup/editor-types.html--multi-root-editor">

### Multi-root editor

The multi-root editor is an editor type that features multiple, separate editable areas. The main difference between using a multi-root editor and using multiple separate editors is the fact that in a multi-root editor, the editors are “connected.” All editable areas of the same editor instance share the same configuration, toolbar, undo stack, and produce one document.

See an [example of the multi-root editor](#ckeditor5/latest/examples/builds/multi-root-editor.html) in action.

Add all roots you need in the editor to the `.create` command. For example:

```
const {
    MultiRootEditor,
    Essentials,
    Bold,
    Italic,
    Font,
    Paragraph
} = CKEDITOR;

MultiRootEditor
    .create( {
        roots: {
            header: { element: document.querySelector( '#header' ) },
            content: { element: document.querySelector( '#content' ) },
            leftSide: { element: document.querySelector( '#left-side' ) },
            rightSide: { element: document.querySelector( '#right-side' ) }
        },
        licenseKey: '<YOUR_LICENSE_KEY>',
        plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
        toolbar: [
            'undo', 'redo', '|', 'bold', 'italic', '|',
            'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

Then, use these roots to place editor windows in the document.

```
<div class="editor">
    <div id="header">
        Header content.
    </div>
</div>
<div class="editor">
    <div id="content">
        Main content.
    </div>
</div>
<div class="boxes">
    <div class="box box-left editor">
        <div id="left-side">
            Left side content.
        </div>
    </div>
    <div class="box box-right editor">
        <div id="right-side">
            Right side content.
        </div>
    </div>
</div>

```

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html">source file: "ckeditor5/latest/getting-started/setup/getting-and-setting-data.html"</a>

## Getting and setting data

In CKEditor 5 there are several ways to load and save data. In this guide, you can learn about the available options and their advantages and disadvantages.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--autosaving">

### Autosaving

One of the best ways to improve the user experience is to automatically save editor data as it changes. This ensures that users do not have to remember to save their data and prevents work loss.

We provide and autosave feature that automatically saves the data (for example sends it to the server) when needed. Please refer to the [Autosave](#ckeditor5/latest/features/autosave.html) guide for details.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--initializing-the-editor-with-data">

### Initializing the editor with data

By default, the editor has the content of the DOM element on which it was initialized on.

```
<div id="editor">
    <!-- This content will appear in the editor if you initialize with this element. -->
    <p>Hello, world!</p>
</div>

```

However, if you cannot alter the HTML or you load the data asynchronously using JavaScript, you can use the `root.initialData` configuration property to set the initial state of the editor.

```
ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ /* ... */ ],
        toolbar: [ /* ... */ ],
        root: {
            initialData: '<p>Hello, world!</p>'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

The [root.initialData](../../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData) property will initialize the editor with the provided data, overriding the content provided at the HTML level.

If you are setting up the editor with integrations like [React](#ckeditor5/latest/getting-started/installation/self-hosted/react/react-default-npm.html), consult the documentation for additional properties provided to initialize the data.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--getting-the-editor-data-with-getdata">

### Getting the editor data with `getData()`

You can use the `getData()` method, if you need to get the editor content on demand, such as for sending it to the server using JavaScript APIs.

```
const data = editor.getData();

```

For that, you need to store the reference to the `editor` because there is no global property. You can do that in multiple ways, for example by assigning the `editor` to a variable defined outside the `then()`'s callback:

```
let editor;

ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ /* ... */ ],
        toolbar: [ /* ... */ ]
    } )
    .then( newEditor => {
        editor = newEditor;
    } )
    .catch( error => {
        console.error( error );
    } );

// Assuming there is a <button id="submit">Submit</button> in your application.
document.querySelector( '#submit' ).addEventListener( 'click', () => {
    const editorData = editor.getData();

    // ...
} );

```

The [getData()](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData) method may accept options that alter the returned content.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--replacing-the-editor-data-with-setdata">

### Replacing the editor data with `setData()`

In some scenarios you may wish to replace the editor content on demand with new data. For this operation use the `setData()` method:

```
editor.setData( '<p>Some text.</p>' );

```

As with getting data, you will need access to the editor’s instance. Refer to the previous section for an example of how to save the instance.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--automatic-integration-with-html-forms">

### Automatic integration with HTML forms

This is the classic way of integrating the editor. It is typically used in simpler CMSes, forums, comment sections, etc.

This approach is **only available in the Classic editor**, and only if the editor was used to replace a `<textarea>` element:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>CKEditor 5 - Classic editor</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
</head>
<body>
    <h1>Classic editor</h1>
    <form action="[URL]" method="post">
        <textarea name="content" id="editor">
            &lt;p&gt;This is some sample content.&lt;/p&gt;
        </textarea>
        <p><input type="submit" value="Submit"></p>
    </form>
    <script>
      	const {
            ClassicEditor,
            Essentials,
            Paragraph,
            Bold,
            Italic
        } = CKEDITOR;

        ClassicEditor
            .create( {
                attachTo: document.querySelector( '#editor' ),
                licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                plugins: [ Essentials, Paragraph, Bold, Italic ],
                toolbar: [ 'bold', 'italic' ]
            } )
            .catch( error => {
                console.error( error );
            } );
    </script>
</body>
</html>

```

Classic editor will automatically update the value of the `<textarea>` element once the user submits the form. You do not need any additional JavaScript code to send the editor data to the server.

In your HTTP server, you can now read the editor data from the `content` variable of the POST request. For instance, in PHP, you can get it in this way:

```
<?php
    $editor_data = $_POST[ 'content' ];
?>

```

When you print the data from the database to a `<textarea>` element in an HTML page, you need to encode it correctly. For instance, if you use PHP then a minimal solution would look like this:

```
<?php
    $data = htmlspecialchars("<p>Hello, world!</p>", ENT_QUOTES, 'UTF-8');
?>

<textarea name="content" id="editor"><?= $data ?></textarea>

```

Thanks to that, the `<textarea>` will be printed out like this:

```
<textarea>&lt;p&gt;Hello, world!&lt;/p&gt;</textarea>

```

Instead of being printed like this:

```
<textarea><p>Hello, world!</p></textarea>

```

While simple content like that mentioned above does not itself require to be encoded, encoding the data will prevent losing text like `<` or `<IMPORTANT>`.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--updating-the-source-element">

### Updating the source element

If the source element is not `<textarea>`, CKEditor 5 clears its content after the editor is destroyed. However, if you would like to enable updating the source element with the output coming from the data pipeline, you can use the [updateSourceElementOnDestroy](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-updateSourceElementOnDestroy) configuration option.

```
ClassicEditor
    .create( {
        // ...
        updateSourceElementOnDestroy: true
    } );

```

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--alerting-users-exiting-the-page">

### Alerting users exiting the page

An additional concern when integrating the editor into your website is that the user may mistakenly leave before saving the data. This problem is automatically handled by the [autosave feature](#ckeditor5/latest/features/autosave.html), but if you do not use it and instead choose different integration methods, you should consider handling these two scenarios:

* The user leaves the page before saving the data (e.g. mistakenly closes a tab or clicks some link).
* The user saved the data, but there are some pending actions like an image upload.

To handle the former situation you can listen to the native [window#beforeunload](https://developer.mozilla.org/en-US/docs/Web/Events/beforeunload) event. The latter situation can be handled by using the CKEditor 5 [PendingActions](../../api/module%5Fcore%5Fpendingactions-PendingActions.html) plugin.

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--demo">

#### Demo

The example below shows how all these mechanisms can be used together to enable or disable a “Save” button and block the user from leaving the page without saving the data.

How to understand this demo:

* The button changes to “Saving…” when the data is being sent to the server or there are any other pending actions (e.g. an image being uploaded).
* You will be asked whether you want to leave the page if an image is being uploaded or the data has not been saved successfully yet. You can test that by dropping a big image into the editor or changing the “HTTP server lag” to a high value (e.g. 9000ms) and clicking the “Save” button. These actions will make the editor “busy” for a longer time – try leaving the page then.

**Server data:**

<a id="ckeditor5/latest/getting-started/setup/getting-and-setting-data.html--snippet-manualsave-console">

```

```

<a id="ckeditor5/latest/getting-started/setup/loading-cdn-resources.html">source file: "ckeditor5/latest/getting-started/setup/loading-cdn-resources.html"</a>

## Loading CDN resources

Loading CKEditor 5 and its plugins from a CDN requires adding the necessary script and style sheet tags to the `<head>` of your page. In some environments, this can be easily done manually by following the [CDN for Vanilla JavaScript](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide.

However, other environments may require more work. It is especially true if you want to load some resources conditionally or dynamically or need to wait for the resources to be loaded before using them.

For this reason, we provide the `useCKEditorCloud` and `loadCKEditorCloud` helper functions to make this process easier. These functions will handle adding the necessary script and style sheet tags to your page, ensure that the resources are only loaded once, and provide access to the data exported by them. This way you can load CKEditor 5 and its plugins from a CDN without worrying about the technical details.

If you use our [React](#ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html) or [Vue.js 3+](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html) integrations, see the [Using the useCKEditorCloud function](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--using-the-useckeditorcloud-function) section. Otherwise, see the [Using the loadCKEditorCloud function](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--using-the-loadckeditorcloud-function) section.

<a id="ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--using-the-useckeditorcloud-function">

### Using the `useCKEditorCloud` function

Our [React](#ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html) and [Vue.js 3+](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html) integrations export a helper function named `useCKEditorCloud` to help you load CDN resources. These helpers are only small wrappers around the `loadCKEditorCloud` function but are designed to better integrate with the specific framework, its lifecycle, and reactivity mechanisms.

Here is an example of how you can use `useCKEditorCloud`:

```
const cloud = useCKEditorCloud( {
    version: '48.0.0',
    premium: true
} );

```

This will add the necessary script and style sheet tags to the page’s `<head>` and update the internal state to reflect the loading status. Depending on the framework, the `useCKEditorCloud` function may return different values. Please refer to the documentation of the specific integration for more details.

Regardless of the framework used, the `useCKEditorCloud` functions always accept the same options, which are described in the [loadCKEditorCloud function options](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--the-loadckeditorcloud-function-options) section.

<a id="ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--using-the-loadckeditorcloud-function">

### Using the `loadCKEditorCloud` function

To use the `loadCKEditorCloud` helper, you need to install the following package:

```
npm install @ckeditor/ckeditor5-integrations-common

```

Then you can use the `loadCKEditorCloud` function like this:

```
import { loadCKEditorCloud } from '@ckeditor/ckeditor5-integrations-common';

const { CKEditor, CKEditorPremiumFeatures } = await loadCKEditorCloud( {
    version: '48.0.0',
    premium: true
} );

```

The `loadCKEditorCloud` function returns a promise that resolves to an object in which each key contains data of the corresponding CDN resources. The exact object shape depends on the options passed to the function.

The options accepted by the `loadCKEditorCloud` function are described in [The loadCKEditorCloud function options](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--the-loadckeditorcloud-function-options) section.

<a id="ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--the-loadckeditorcloud-function-options">

### The `loadCKEditorCloud` function options

The `loadCKEditorCloud` function (and `useCKEditorCloud` functions which are small wrappers around it) accepts an object with the following properties:

* `version` (required) – The version of CKEditor 5 and premium features (if `premium` option is set to `true`) to load.
* `translations` (optional) – An array of language codes to load translations for.
* `premium` (optional) – A Boolean value that indicates whether to load premium plugins. \[1\]
* `ckbox` (optional) – Configuration for loading CKBox integration. \[1\]
* `plugins` (optional) – Configuration for loading additional plugins. The object should have the global plugin name as keys and the plugin configuration as values. \[1\]
* `injectedHtmlElementsAttributes` (optional) – An object with attributes that will be added to the `<script>` and `<link>` tags that are injected into the page. This can be used to add attributes like `integrity` or `crossorigin` to the tags. By default, it is set to `{ crossorigin: 'anonymous' }`.

Here is an example showing all the available options:

```
{
    version: '48.0.0',
    translations: [ 'es', 'de' ],
    premium: true,
    ckbox: {
        version: '2.11.0',
        theme: 'lark' // Optional, default 'lark'.
    },
    plugins: {
        ThirdPartyPlugin: [
            'https://cdn.example.com/plugin.umd.js',
            'https://cdn.example.com/plugin.css'
        ],
        AnotherPlugin: () => import( './path/to/plugin.umd.js' ),
        YetAnotherPlugin: {
            scripts: [ 'https://cdn.example.com/plugin.umd.js' ],
            stylesheets: [ 'https://cdn.example.com/plugin.css' ],

            // Optional, if it's not passed then the name of the plugin will be used.
            checkPluginLoaded: () => window.PLUGIN_NAME
        }
    }
}

```

Note that unless the `checkPluginLoaded` callback is used, the keys in the `plugins` object must match the names of the global object used by the plugins. As shown in the example above, we used the `checkPluginLoaded` to be able to access the plugin using the `YetAnotherPlugin` key, while the plugin itself assigns to the `window.PLUGIN_NAME` property.

With this configuration, the object returned by this function will have the following properties:

* `CKEditor` – The base CKEditor 5 library.
* `CKEditorPremiumFeatures` – Premium features for CKEditor 5\. This option is only available when `premium` is set to `true`.
* `CKBox` – The CKBox integration. This option is only available when the `ckbox` option is provided.
* `ThirdPartyPlugin` – The custom plugin registered in the `plugins` option.
* `AnotherPlugin` – The custom plugin registered in the `plugins` option.
* `YetAnotherPlugin` – The custom plugin registered in the `plugins` option.

<a id="ckeditor5/latest/getting-started/setup/menubar.html">source file: "ckeditor5/latest/getting-started/setup/menubar.html"</a>

## Menu bar

The menu bar is a user interface component that gives you access to all features provided by the editor, organized in menus and categories. This familiar experience popular in large editing desktop and online packages improves usability of the editor.

As the menu bar gathers all the editor features, the toolbar can be simple and tidy, providing only the most essential and commonly used features. This is especially welcome in heavily-featured editor integrations.

For your convenience, the menu bar provides a [default preset structure](../../api/module%5Fui%5Fmenubar%5Futils.html#constant-DefaultMenuBarItems), based on the plugins loaded in the editor. However, you can arrange it to suit your needs, remove unnecessary items, as well as add menu items related to your custom features.

<a id="ckeditor5/latest/getting-started/setup/menubar.html--demo">

### Demo

The demo below presents all items available in the menu bar preset settings.

You can easily remove some presets or add more items, including menu items for custom features. The structure can also be arranged to suit particular needs.

<a id="ckeditor5/latest/getting-started/setup/menubar.html--enabling-the-menu-bar">

### Enabling the menu bar

The menu bar is available in all editor types. Usage will vary depending on used editor type.

<a id="ckeditor5/latest/getting-started/setup/menubar.html--classic-editor-and-inline-editor">

#### Classic editor and Inline editor

The menu bar is disabled by default. To make it available in your editor, set the [config.menuBar.isVisible](../../api/module%5Fui%5Fmenubar%5Fmenubarview-MenuBarConfig.html) property to `true`. This will turn on the menu bar with a default set of features. The menu bar is located right above the editor toolbar.

```
ClassicEditor
    .create( {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ],
        menuBar: {
            isVisible: true
        }
    } );

```

<a id="ckeditor5/latest/getting-started/setup/menubar.html--other-editor-types">

#### Other editor types

When using the Decoupled, Balloon or Multi-root editor, you will need to insert the menu bar in a desired place yourself. The menu bar HTML element is available under the [editor.ui.view.menuBarView.element](../../api/module%5Fui%5Feditorui%5Feditoruiview-EditorUIView.html#member-menuBarView) property.

```
<div id="menuBarContainer"></div>
<div id="editor"><p>Document content.</p></div>

```

```
DecoupledEditor
    .create( {
        // ... Other configuration options ...
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ],
    } )
    .then( editor => {
        document.querySelector( '#menuBarContainer' ).appendChild( editor.ui.view.menuBarView.element );
    } );

```

<a id="ckeditor5/latest/getting-started/setup/menubar.html--configuration">

### Configuration

The menu bar can be configured using the [config.menuBar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar) option and its `config.menuBar.removeItems` and `config.menuBar.addItems` properties. Please refer to the [config.menuBar API documentation](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar) for details on how to do it.

<a id="ckeditor5/latest/getting-started/setup/menubar.html--adding-custom-buttons-to-the-menu-bar">

### Adding custom buttons to the menu bar

To add custom buttons or other components to the menu bar, follow these steps:

1. Create a new UI component using [editor.ui.componentFactory](../../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html). Define its behavior and appearance.
2. Use [editor.ui.extendMenuBar()](../../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#function-extendMenuBar) method to add your component to the menu bar at a desired position.

Here’s an example of a custom plugin that adds a button to the menu bar inside the “Format” menu, after the “Bold” button:

<a id="ckeditor5/latest/getting-started/setup/menubar.html--contribute">

### Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ui>.

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html">source file: "ckeditor5/latest/getting-started/setup/optimizing-build-size.html"</a>

## Optimizing build size

By default, the CKEditor 5 packages are well-optimized. Most of the code is tree-shakeable, meaning that most unused (or “dead”) code is removed during the build process. However, there are additional steps you can take to further optimize the build size, as the default installation methods were designed to be as developer-friendly as possible, not necessarily to produce the smallest possible build.

The build size optimization is only possible when using the npm build and module bundler. The CDN build cannot be optimized this way, as it is intended to include all plugins, features, and styles.

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html--how-to-optimize-the-build-size">

### How to optimize the build size

To optimize the build size, you only need to make a few changes to the way you import the editor, styles, and optionally the translations, compared to what was shown in the [Quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide. You do not need to change anything in the editor configuration or in the way you use the editor.

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html--code-imports">

#### Code imports

The first step in optimizing build size is to import only the editor features you need, as adding more plugins to the editor configuration will increase build size.

The next step is to change the way you import the editor features. Currently, you are probably importing them from the following packages:

```
import { /* ... */ } from 'ckeditor5';
import { /* ... */ } from 'ckeditor5-premium-features';

```

These two packages export all the editor features, and most are tree-shakeable. However, some code may be added to the build even if it is not used. To ensure that the unused code is not imported, you can import the editor features directly from the packages that contain them.

For example, if you are using the classic editor type with the bold, italic, and table features, you can change the imports like this:

```
- import { ClassicEditor, Bold, Italic and Table } from 'ckeditor5';

+ import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic/dist/index.js';
+ import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles/dist/index.js';
+ import { Table } from '@ckeditor/ckeditor5-table/dist/index.js';

```

To find the correct package names, go to the [plugins and HTML output](#ckeditor5/latest/framework/architecture/plugins.html--plugins-and-html-output) guide, find the plugin name and get the file path shown under the package name.

Alternatively, if you are using an IDE with TypeScript support, you can use the `Go to Definition` feature to find the package names.

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html--styles">

#### Styles

Currently, you probably import one or both of the following style sheets, depending on whether or not you use the premium features:

```
import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

```

Such imports are neat because they are easily readable and easy to follow. However, these style sheets contain all the styles for all the plugins and features. If you want to reduce the build size, you can import only the core styles alongside the styles for used plugins.

First, import the core styles. They are all needed for the editor to work properly, and the order of the imports matters, so make sure to import them in the following order:

```
// Import the core styles.
import '@ckeditor/ckeditor5-ui/dist/index.css';
import '@ckeditor/ckeditor5-clipboard/dist/index.css';
import '@ckeditor/ckeditor5-core/dist/index.css';
import '@ckeditor/ckeditor5-engine/dist/index.css';
import '@ckeditor/ckeditor5-enter/dist/index.css';
import '@ckeditor/ckeditor5-paragraph/dist/index.css';
import '@ckeditor/ckeditor5-select-all/dist/index.css';
import '@ckeditor/ckeditor5-typing/dist/index.css';
import '@ckeditor/ckeditor5-undo/dist/index.css';
import '@ckeditor/ckeditor5-upload/dist/index.css';
import '@ckeditor/ckeditor5-utils/dist/index.css';
import '@ckeditor/ckeditor5-watchdog/dist/index.css';
import '@ckeditor/ckeditor5-widget/dist/index.css';

```

Then, import the styles for the plugins that you use. For example, if you use the bold, italic, and table features, you can import just the styles for those features:

```
// Import the styles for the features that you use.
import '@ckeditor/ckeditor5-basic-styles/dist/index.css';
import '@ckeditor/ckeditor5-table/dist/index.css';
// ...

```

Regarding plugin styles, the rule of thumb is to import the styles from all the individual packages from which you import the editor features. For example, if you import the bold feature from `@ckeditor/ckeditor5-basic-styles/dist/index.js`, you should also import `@ckeditor/ckeditor5-basic-styles/dist/index.css`.

You may notice that some plugin style sheets are empty. This is intentional, as some plugins do not have styles now but may have them in the future. Adding the imports now will ensure that you do not accidentally miss some styles if this happens. Importing empty style sheets does not increase the build size.

If you use separate editor and content styles, as described in the [Editor and content styles](#ckeditor5/latest/getting-started/setup/css.html) guide, you can still add `-content` and `-editor` suffixes to the style paths:

```
// All styles
import '@ckeditor/ckeditor5-clipboard/dist/index.css';

// Content styles
import '@ckeditor/ckeditor5-clipboard/dist/index-content.css';

// Editor styles
import '@ckeditor/ckeditor5-clipboard/dist/index-editor.css';

```

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html--translations">

#### Translations

By default, the editor comes with American English translations, so if you use it, you do not need to import any additional translations, thus reducing the size of the build.

However, if you need to support other languages, the [Setting the UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) guide shows how to import additional translations.

For example, if you need to support Polish, you can import the Polish translations like this:

```
import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

```

However, similarly to the styles, these files contain translations for all plugins and features. If you want to reduce the build size, you can import just the core translations and the translations for the plugins you use.

First, import the core translations. They are all needed for the editor to work properly:

```
// Import the core translations.
import clipboardTranslations from '@ckeditor/ckeditor5-clipboard/dist/translations/<LANGUAGE>.js';
import coreTranslations from '@ckeditor/ckeditor5-core/dist/translations/<LANGUAGE>.js';
import enterTranslations from '@ckeditor/ckeditor5-enter/dist/translations/<LANGUAGE>.js';
import selectAllTranslations from '@ckeditor/ckeditor5-select-all/dist/translations/<LANGUAGE>.js';
import uiTranslations from '@ckeditor/ckeditor5-ui/dist/translations/<LANGUAGE>.js';
import undoTranslations from '@ckeditor/ckeditor5-undo/dist/translations/<LANGUAGE>.js';
import uploadTranslations from '@ckeditor/ckeditor5-upload/dist/translations/<LANGUAGE>.js';
import widgetTranslations from '@ckeditor/ckeditor5-widget/dist/translations/<LANGUAGE>.js';

```

Then, import the translations for the plugins that you use. For example, if you use the bold, italic and table features, you can only import the translations for those features:

```
// Import the translations for the features that you use.
import basicStylesTranslations from '@ckeditor/ckeditor5-basic-styles/dist/translations/<LANGUAGE>.js';
import tableTranslations from '@ckeditor/ckeditor5-table/dist/translations/<LANGUAGE>.js';

```

As with styles, the rule of thumb is to import translations from all the individual packages from which you import the editor features. For example, if you import the bold feature from the `@ckeditor/ckeditor5-basic-styles/dist/index.js` package, you should also import the translations from the `@ckeditor/ckeditor5-basic-styles/translations/<LANGUAGE>.js` file.

Some plugins may not have translations. In such cases, you do not need to import translations for them.

<a id="ckeditor5/latest/getting-started/setup/optimizing-build-size.html--the-result">

### The result

Let’s see how the build size changes after applying the above optimizations to a sample project with the classic editor, free and premium features, plus Polish translations.

Code before optimization 

```
import {
    ClassicEditor,
    Essentials,
    CKFinderUploadAdapter,
    Autoformat,
    Bold,
    Italic,
    BlockQuote,
    CKBox,
    CKFinder,
    Heading,
    Image,
    ImageCaption,
    ImageStyle,
    ImageToolbar,
    ImageUpload,
    PictureEditing,
    Indent,
    Link,
    List,
    MediaEmbed,
    Paragraph,
    PasteFromOffice,
    Table,
    TableToolbar,
    TextTransformation,
    CloudServices,
    Mention
} from 'ckeditor5';

import { CaseChange, SlashCommand } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import commercialTranslations from 'ckeditor5-premium-features/translations/pl.js';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

ClassicEditor.create( {
    attachTo: document.querySelector( '#editor' ),
    plugins: [
        Essentials,
        CKFinderUploadAdapter,
        Autoformat,
        Bold,
        Italic,
        BlockQuote,
        CKBox,
        CKFinder,
        CloudServices,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        PictureEditing,
        Table,
        TableToolbar,
        TextTransformation,
        Mention,

        CaseChange,
        SlashCommand
    ],
    licenseKey: '<YOUR_LICENSE_KEY>', // Replace this with your license key.
    toolbar: {
        items: [
            'undo', 'redo',
            '|', 'heading',
            '|', 'bold', 'italic',
            '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',
            '|', 'bulletedList', 'numberedList', 'outdent', 'indent', 'caseChange'
        ]
    },
    image: {
        toolbar: [
            'imageStyle:inline',
            'imageStyle:block',
            'imageStyle:side',
            '|',
            'toggleImageCaption',
            'imageTextAlternative'
        ]
    },
    table: {
        contentToolbar: [
            'tableColumn',
            'tableRow',
            'mergeTableCells'
        ]
    },
    translations: [
        coreTranslations,
        commercialTranslations
    ],
    language: 'pl'
} );

```

Code after optimization 

```
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic/dist/index.js';
import { Essentials } from '@ckeditor/ckeditor5-essentials/dist/index.js';
import { CKFinderUploadAdapter } from '@ckeditor/ckeditor5-adapter-ckfinder/dist/index.js';
import { Autoformat } from '@ckeditor/ckeditor5-autoformat/dist/index.js';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles/dist/index.js';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote/dist/index.js';
import { CKBox } from '@ckeditor/ckeditor5-ckbox/dist/index.js';
import { CKFinder } from '@ckeditor/ckeditor5-ckfinder/dist/index.js';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services/dist/index.js';
import { Heading } from '@ckeditor/ckeditor5-heading/dist/index.js';
import { Image, ImageCaption, ImageStyle, ImageToolbar, ImageUpload, PictureEditing } from '@ckeditor/ckeditor5-image/dist/index.js';
import { Indent } from '@ckeditor/ckeditor5-indent/dist/index.js';
import { Link } from '@ckeditor/ckeditor5-link/dist/index.js';
import { List } from '@ckeditor/ckeditor5-list/dist/index.js';
import { MediaEmbed } from '@ckeditor/ckeditor5-media-embed/dist/index.js';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph/dist/index.js';
import { PasteFromOffice } from '@ckeditor/ckeditor5-paste-from-office/dist/index.js';
import { Table, TableToolbar } from '@ckeditor/ckeditor5-table/dist/index.js';
import { TextTransformation } from '@ckeditor/ckeditor5-typing/dist/index.js';
import { Mention } from '@ckeditor/ckeditor5-mention/dist/index.js';
import { CaseChange } from '@ckeditor/ckeditor5-case-change/dist/index.js';
import { SlashCommand } from '@ckeditor/ckeditor5-slash-command/dist/index.js';

import clipboardTranslations from '@ckeditor/ckeditor5-clipboard/dist/translations/pl.js';
import coreTranslations from '@ckeditor/ckeditor5-core/dist/translations/pl.js';
import enterTranslations from '@ckeditor/ckeditor5-enter/dist/translations/pl.js';
import selectAllTranslations from '@ckeditor/ckeditor5-select-all/dist/translations/pl.js';
import uiTranslations from '@ckeditor/ckeditor5-ui/dist/translations/pl.js';
import undoTranslations from '@ckeditor/ckeditor5-undo/dist/translations/pl.js';
import uploadTranslations from '@ckeditor/ckeditor5-upload/dist/translations/pl.js';
import widgetTranslations from '@ckeditor/ckeditor5-widget/dist/translations/pl.js';
import autoformatTranslations from '@ckeditor/ckeditor5-autoformat/dist/translations/pl.js';
import basicStylesTranslations from '@ckeditor/ckeditor5-basic-styles/dist/translations/pl.js';
import blockQuoteTranslations from '@ckeditor/ckeditor5-block-quote/dist/translations/pl.js';
import ckboxTranslations from '@ckeditor/ckeditor5-ckbox/dist/translations/pl.js';
import ckfinderTranslations from '@ckeditor/ckeditor5-ckfinder/dist/translations/pl.js';
import headingTranslations from '@ckeditor/ckeditor5-heading/dist/translations/pl.js';
import imageTranslations from '@ckeditor/ckeditor5-image/dist/translations/pl.js';
import indentTranslations from '@ckeditor/ckeditor5-indent/dist/translations/pl.js';
import linkTranslations from '@ckeditor/ckeditor5-link/dist/translations/pl.js';
import listTranslations from '@ckeditor/ckeditor5-list/dist/translations/pl.js';
import mediaEmbedTranslations from '@ckeditor/ckeditor5-media-embed/dist/translations/pl.js';
import tableTranslations from '@ckeditor/ckeditor5-table/dist/translations/pl.js';
import caseChangeTranslations from '@ckeditor/ckeditor5-case-change/dist/translations/pl.js';
import slashCommandTranslations from '@ckeditor/ckeditor5-slash-command/dist/translations/pl.js';

import '@ckeditor/ckeditor5-clipboard/dist/index.css';
import '@ckeditor/ckeditor5-core/dist/index.css';
import '@ckeditor/ckeditor5-engine/dist/index.css';
import '@ckeditor/ckeditor5-enter/dist/index.css';
import '@ckeditor/ckeditor5-paragraph/dist/index.css';
import '@ckeditor/ckeditor5-select-all/dist/index.css';
import '@ckeditor/ckeditor5-typing/dist/index.css';
import '@ckeditor/ckeditor5-ui/dist/index.css';
import '@ckeditor/ckeditor5-undo/dist/index.css';
import '@ckeditor/ckeditor5-upload/dist/index.css';
import '@ckeditor/ckeditor5-utils/dist/index.css';
import '@ckeditor/ckeditor5-watchdog/dist/index.css';
import '@ckeditor/ckeditor5-widget/dist/index.css';
import '@ckeditor/ckeditor5-editor-classic/dist/index.css';
import '@ckeditor/ckeditor5-essentials/dist/index.css';
import '@ckeditor/ckeditor5-adapter-ckfinder/dist/index.css';
import '@ckeditor/ckeditor5-autoformat/dist/index.css';
import '@ckeditor/ckeditor5-basic-styles/dist/index.css';
import '@ckeditor/ckeditor5-block-quote/dist/index.css';
import '@ckeditor/ckeditor5-ckbox/dist/index.css';
import '@ckeditor/ckeditor5-ckfinder/dist/index.css';
import '@ckeditor/ckeditor5-cloud-services/dist/index.css';
import '@ckeditor/ckeditor5-heading/dist/index.css';
import '@ckeditor/ckeditor5-image/dist/index.css';
import '@ckeditor/ckeditor5-indent/dist/index.css';
import '@ckeditor/ckeditor5-link/dist/index.css';
import '@ckeditor/ckeditor5-list/dist/index.css';
import '@ckeditor/ckeditor5-media-embed/dist/index.css';
import '@ckeditor/ckeditor5-paste-from-office/dist/index.css';
import '@ckeditor/ckeditor5-table/dist/index.css';
import '@ckeditor/ckeditor5-mention/dist/index.css';
import '@ckeditor/ckeditor5-case-change/dist/index.css';
import '@ckeditor/ckeditor5-slash-command/dist/index.css';

ClassicEditor.create( {
    attachTo: document.querySelector( '#editor' ),
    plugins: [
        Essentials,
        CKFinderUploadAdapter,
        Autoformat,
        Bold,
        Italic,
        BlockQuote,
        CKBox,
        CKFinder,
        CloudServices,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        PictureEditing,
        Table,
        TableToolbar,
        TextTransformation,
        Mention,

        CaseChange,
        SlashCommand
    ],
    licenseKey: '<YOUR_LICENSE_KEY>', // Replace this with your license key.
    toolbar: {
        items: [
            'undo', 'redo',
            '|', 'heading',
            '|', 'bold', 'italic',
            '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',
            '|', 'bulletedList', 'numberedList', 'outdent', 'indent', 'caseChange'
        ]
    },
    image: {
        toolbar: [
            'imageStyle:inline',
            'imageStyle:block',
            'imageStyle:side',
            '|',
            'toggleImageCaption',
            'imageTextAlternative'
        ]
    },
    table: {
        contentToolbar: [
            'tableColumn',
            'tableRow',
            'mergeTableCells'
        ]
    },
    translations: [
        clipboardTranslations,
        coreTranslations,
        enterTranslations,
        selectAllTranslations,
        uiTranslations,
        undoTranslations,
        uploadTranslations,
        widgetTranslations,
        autoformatTranslations,
        basicStylesTranslations,
        blockQuoteTranslations,
        ckboxTranslations,
        ckfinderTranslations,
        headingTranslations,
        imageTranslations,
        indentTranslations,
        linkTranslations,
        listTranslations,
        mediaEmbedTranslations,
        tableTranslations,
        caseChangeTranslations,
        slashCommandTranslations,
    ],
    language: 'pl'
} );

```

The build size of the project before and after the optimizations is as follows:

|                    | Before optimization | After optimization | Improvement |
| ------------------ | ------------------- | ------------------ | ----------- |
| JavaScript gzipped | 269.18 kB           | 257.31 kB          | \-4.41%     |
| CSS gzipped        | 64.98 kB            | 30.80 kB           | \-52.60%    |

Thanks to the above optimizations, we were able to reduce the total build size (JavaScript + CSS) by `46,05 kB` gzipped, which in effect gives us \~85% of the original size. These results will vary depending on the editor features and bundler you use.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html">source file: "ckeditor5/latest/getting-started/setup/toolbar.html"</a>

## Editor toolbars

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--main-editor-toolbar">

### Main editor toolbar

The toolbar is the most basic user interface element of CKEditor 5 that gives you convenient access to all its features. It has buttons and dropdowns that you can use to format, manage, insert, and change elements of your content.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--demo">

#### Demo

Below is a sample toolbar with a basic set of features. Toolbar items can be easily added or removed. Read on to learn how to do that.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--basic-toolbar-configuration">

#### Basic toolbar configuration

The toolbar offers a flexible arrangement, achieved through configuration. Please note, that using [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) makes this task significantly easier.

The following example may give you a general idea:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ]
    } )
    .catch( error => {
        console.log( error );
    } );

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--separating-toolbar-items">

#### Separating toolbar items

You can use `'|'` to create a separator between groups of toolbar items. This works in both the basic and extended configuration formats.

Below you can find an example of a simple toolbar with button grouping. The group separators (`'|'`) set in the configuration help organize the toolbar.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--extended-toolbar-configuration-format">

#### Extended toolbar configuration format

There are two available toolbar configuration formats:

Basic:

```
toolbar: [ 'bold', 'italic', '|', 'undo', 'redo', '|', 'numberedList', 'bulletedList' ]

```

And extended:

```
toolbar: {
    items: [ 'bold', 'italic', '|', 'undo', 'redo', '|', 'numberedList', 'bulletedList' ]
}

```

You can use the extended [toolbar configuration](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar) format to access additional options:

```
toolbar: {
    items: [
        'undo', 'redo',
        '|',
        'heading',
        '|',
        'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|',
        'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '|',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|',
        'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: false
}

```

* **[items](../../api/module%5Fcore%5Feditor%5Feditorconfig-ToolbarConfig.html#member-items)** – An array of toolbar item names. Most of the components (buttons, dropdowns, etc.) that you can use as toolbar items are described in the [Features](#ckeditor5/latest/features/index.html) section. A full list is defined in [editor.ui.componentFactory](../../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html) and can be listed using the following snippet: `Array.from( editor.ui.componentFactory.names() )`. Besides button names, you can also use the dedicated separators for toolbar groups (`'|'`) and toolbar lines (`'-'`).
* **[removeItems](../../api/module%5Fcore%5Feditor%5Feditorconfig-ToolbarConfig.html#member-removeItems)** – An array of toolbar item names. With this setting, you can change the default toolbar configuration without the need to define the entire list. You can specify a couple of buttons that you want to remove instead of specifying all the buttons you want to keep. If, after removing an item, the toolbar will have two or more consecutive separators (`'|'`), the duplicates will be removed automatically.
* **[shouldNotGroupWhenFull](../../api/module%5Fcore%5Feditor%5Feditorconfig-ToolbarConfig.html#member-shouldNotGroupWhenFull)** – When set to `true`, the toolbar will stop grouping items and let them wrap to the next line when there is not enough space to display them in a single row. This setting is `false` by default, which enables item grouping.

The demo below presents the “regular” toolbar look with `shouldNotGroupWhenFull` set to `false`. If there are more toolbar items than can fit in the toolbar in the current display width, some items get hidden. You can access them by clicking the show more items button .

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--multiline-wrapping-toolbar">

#### Multiline (wrapping) toolbar

In the [extended toolbar configuration format](#ckeditor5/latest/getting-started/setup/toolbar.html--extended-toolbar-configuration-format), it is also possible to arrange toolbar items into multiple lines. Here is how to achieve this:

* Set the `shouldNotGroupWhenFull` option to `true`, so items will not be grouped when the toolbar overflows. They will wrap to the new line instead.
* Additionally, you can use the `'-'` separator inside the item list to set the breaking point explicitly.

```
toolbar: {
    items: [ 'bold', 'italic', '|', 'undo', 'redo', '-', 'numberedList', 'bulletedList' ],
    shouldNotGroupWhenFull: true
}

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--automatic-toolbar-wrapping">

##### Automatic toolbar wrapping

When you set `shouldNotGroupWhenFull` to `true`, by default the toolbar items are automatically wrapped into a new line once they do not fit the editor width. The mechanism is automatic and only wraps excess items. Notice that while the toolbar group separators `'|'` are preserved, the groups may be split when they overflow.

```
toolbar: {
    items: [
        'undo', 'redo',
        '|',
        'heading',
        '|',
        'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|',
        'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '|',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|',
        'alignment',
        '|',
        'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: true
}

```

See how it works in practice. Play with the browser window width to see how the buttons behave when the toolbar gets wrapped into multiple lines.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--explicit-wrapping-breakpoint">

##### Explicit wrapping breakpoint

Setting an explicit break point in the toolbar configuration with `'-'` lets you create your own predefined multiline toolbar configuration. Toolbar items will then be grouped and put in lines as declared in the configuration.

```
toolbar: {
    items: [
        'undo', 'redo',
        '|', 'heading',
        '|', 'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|', 'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '-', // break point
        '|', 'alignment',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|', 'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: true
}

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--grouping-toolbar-items-in-dropdowns-nested-toolbars">

#### Grouping toolbar items in dropdowns (nested toolbars)

To save space in your toolbar or arrange the features thematically, you can group several items into a dropdown. For instance, check out the following configuration:

```
toolbar: [
    {
        label: 'More basic styles',
        icon: 'threeVerticalDots',
        items: [ 'strikethrough', 'superscript', 'subscript' ]
    },
    // More of toolbar's configuration.
    // ...
]

```

It will create a “Basic styles” dropdown with a three vertical dots icon  containing the additional basic text styles buttons set. You can test it in the demo below along with a few more toolbar dropdowns.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--customization">

##### Customization

You can customize the look of the dropdown by configuring additional properties, such as the icon, label, or tooltip text.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--displaying-the-label">

##### Displaying the label

You can control the way the UI element is displayed. For instance, to hide the icon and to display the label, you can use the following configuration:

```
{
    label: 'Basic styles',
    // Show the textual label of the dropdown.
    // Note that the "icon" property is not configured and defaults to three dots.
    withText: true,
    items: [ 'bold', 'italic', 'strikethrough', 'superscript', 'subscript' ]
}

```

**Note**: The label will also automatically show up if the `icon` is `false` ([learn more](#ckeditor5/latest/getting-started/setup/toolbar.html--changing-the-icon)).

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--changing-the-icon">

##### Changing the icon

You can use one of the icons listed below for your dropdown:

| Icon name                         | Preview |
| --------------------------------- | ------- |
| 'threeVerticalDots' **(default)** |         |
| 'alignLeft'                       |         |
| 'bold'                            |         |
| 'importExport'                    |         |
| 'paragraph'                       |         |
| 'text'                            |         |
| 'plus'                            |         |
| 'dragIndicator'                   |         |
| 'pilcrow'                         |         |

* The default icons are loaded from the `ckeditor5-core` package.
* If no icon is specified, `'threeVerticalDots'` will be used as a default.
* If `icon: false` is configured, no icon will be displayed and the text label will show up instead.
* You can set a custom icon for the dropdown by [passing an SVG string](#ckeditor5/latest/framework/architecture/ui-library.html--setting-label-icon-and-tooltip).

Here is an example:

```
toolbar: [
    'undo', 'redo', '|',
    {
        // This dropdown uses a default icon because none was specified.
        label: 'Fonts',
        items: [ 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor' ]
    },
    '|',
    {
        label: 'A drop-down with a custom icon',
        // If you want your icon to change the color dynamically (for example, when opened)
        // avoid fill="..." and stroke="..." styling attributes.
        // Use solid shapes and avoid paths with strokes.
        // eslint-disable-next-line @stylistic/max-len
        icon: '<svg viewBox="0 0 68 64" xmlns="http://www.w3.org/2000/svg"><g fill="none" fill-rule="evenodd"><path d="M43.71 11.025a11.508 11.508 0 0 0-1.213 5.159c0 6.42 5.244 11.625 11.713 11.625.083 0 .167 0 .25-.002v16.282a5.464 5.464 0 0 1-2.756 4.739L30.986 60.7a5.548 5.548 0 0 1-5.512 0L4.756 48.828A5.464 5.464 0 0 1 2 44.089V20.344c0-1.955 1.05-3.76 2.756-4.738L25.474 3.733a5.548 5.548 0 0 1 5.512 0l12.724 7.292z" fill="#FFF"/><path d="M45.684 8.79a12.604 12.604 0 0 0-1.329 5.65c0 7.032 5.744 12.733 12.829 12.733.091 0 .183-.001.274-.003v17.834a5.987 5.987 0 0 1-3.019 5.19L31.747 63.196a6.076 6.076 0 0 1-6.037 0L3.02 50.193A5.984 5.984 0 0 1 0 45.003V18.997c0-2.14 1.15-4.119 3.019-5.19L25.71.804a6.076 6.076 0 0 1 6.037 0L45.684 8.79zm-29.44 11.89c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h18.479c.833 0 1.509-.67 1.509-1.498v-.715c0-.827-.676-1.498-1.51-1.498H16.244zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm41.191-14.459c-5.835 0-10.565-4.695-10.565-10.486 0-5.792 4.73-10.487 10.565-10.487C63.27 3.703 68 8.398 68 14.19c0 5.791-4.73 10.486-10.565 10.486v-.001z" fill="#1EBC61" fill-rule="nonzero"/><path d="M60.857 15.995c0-.467-.084-.875-.251-1.225a2.547 2.547 0 0 0-.686-.88 2.888 2.888 0 0 0-1.026-.531 4.418 4.418 0 0 0-1.259-.175c-.134 0-.283.006-.447.018-.15.01-.3.034-.446.07l.075-1.4h3.587v-1.8h-5.462l-.214 5.06c.319-.116.682-.21 1.089-.28.406-.071.77-.107 1.088-.107.218 0 .437.021.655.063.218.041.413.114.585.218s.313.244.422.419c.109.175.163.391.163.65 0 .424-.132.745-.396.961a1.434 1.434 0 0 1-.938.325c-.352 0-.656-.1-.912-.3-.256-.2-.43-.453-.523-.762l-1.925.588c.1.35.258.664.472.943.214.279.47.514.767.706.298.191.63.339.995.443.365.104.749.156 1.151.156.437 0 .86-.064 1.272-.193.41-.13.778-.323 1.1-.581a2.8 2.8 0 0 0 .775-.981c.193-.396.29-.864.29-1.405h-.001z" fill="#FFF" fill-rule="nonzero"/></g></svg>',
        items: [ 'bold', 'italic', 'strikethrough', 'superscript', 'subscript' ]
    },
    '|',
    {
        // A "plus" sign icon works best for content insertion tools.
        label: 'Insert',
        icon: 'plus',
        items: [ 'uploadImage', 'insertTable' ]
    },
    '|',
    {
        // This dropdown has the icon disabled and a text label instead.
        label: 'Lists',
        icon: false,
        items: [ 'bulletedList', 'numberedList', 'todoList' ]
    }
],

```

And here is the effect:

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--customizing-the-tooltip">

##### Customizing the tooltip

By default, the tooltip of the button shares its text with the label. You can customize it to better describe your dropdown and make it more accessible by using the [tooltip](../../api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html#member-tooltip) property:

```
toolbar: [
    {
        label: 'Others',
        tooltip: 'Basic formatting features',
        items: [ 'bold', 'italic' ]
    },
    '|',
    'undo', 'redo'
]

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--listing-available-items">

##### Listing available items

You can use the following snippet to retrieve all toolbar items available in your editor:

```
Array.from( editor.ui.componentFactory.names() );

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--adding-a-custom-button">

##### Adding a custom button

Refer to the [step-by-step tutorial](#ckeditor5/latest/framework/tutorials/crash-course/editor.html) to learn how to build a custom plugin, register its button, and add it to the toolbar configuration.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--decoupled-editor">

#### Decoupled editor

When using the Decoupled editor, you will need to insert the menu bar in a desired place yourself. The menu bar HTML element is available under the `editor.ui.view.toolbar.element` property.

```
    <div id="toolbarContainer"></div>
    <div id="editor"><p>Document content.</p></div>

```

```
DecoupledEditor
    .create( {
        root: {
            element: document.querySelector( '#editor' ),
        },
        // ... Other configuration options ...
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ],
    } )
    .then( editor => {
        document.querySelector( '#toolbarContainer' ).appendChild( editor.ui.view.toolbar.element );
    } );

```

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--balloon-toolbar">

#### Balloon toolbar

A ballon toolbar is a special instance of the main toolbar, available in the [Balloon and ballon block](#ckeditor5/latest/getting-started/setup/editor-types.html--balloon-editor-and-balloon-block-editor) editors. Instead of being fixed to the editing area, it pops up when the user selects some content and provides a toolset for editing as pictured below.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar">

### Block toolbar

The block toolbar provides an additional configurable toolbar on the left-hand side of the content area, useful when the main toolbar is not accessible (for example in certain layouts, like balloon block editor).

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--demo-2">

#### Demo

This demo presents a limited set of features. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--additional-feature-information">

#### Additional feature information

To access the block toolbar, you need to click the button with braille pattern dots icon  on the left-hand side of the content area (the gutter). The button appears next to the selected block element (for example, a paragraph), following the caret as the user edits the content and navigates the document.

The icon  is also a handle to drag blocks of content around the editor. Click a heading in the demo above and drag it all the way down between the following paragraphs to see this functionality in action.

The block toolbar complements the [balloon editor type](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) where it falls short, for example when you must insert some content (like an image), but the selection is collapsed, so you cannot access the toolbar. It can, however, be added to any type of editor and configure accordingly (see below).

See the [balloon block editor example](#ckeditor5/latest/examples/builds/balloon-block-editor.html) page, too.

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar-installation">

#### Block toolbar installation

To add this feature to your editor, add the `BlockToolbar` to your plugin list and configure the feature using the `blockToolbar` property:

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar-configuration">

#### Block toolbar configuration

The content of the block toolbar can be defined using the [blockToolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-blockToolbar) configuration. It is similar to the regular toolbar UI items list.

```
blockToolbar: {
    items: [
        'bold',
        'italic',
        'link'
    ]
}

```

See the [installation instructions](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar-installation) for a more advanced example.

To adjust the position of the block toolbar button to match the styles of your website, use the CSS `transform` property:

```
.ck.ck-block-toolbar-button {
    transform: translateX( -10px );
}

```

If you plan to run the editor in a right–to–left (RTL) language, keep in mind the button will be attached to the **right** boundary of the editable area. In that case, make sure the CSS position adjustment works properly by adding the following styles:

```
.ck[dir="rtl"] .ck-block-toolbar-button {
    transform: translateX( 10px );
}

```

You can use the `shouldNotGroupWhenFull` [configuration option](#ckeditor5/latest/getting-started/setup/toolbar.html--multiline-wrapping-toolbar) to prevent [automatic items grouping](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar) in the block toolbar.

You can also change the current default toolbar icon `'dragIndicator'`  by choosing predefined icon from [icon list](#ckeditor5/latest/getting-started/setup/toolbar.html--changing-the-icon) using the `icon` option or by passing a `SVG` string:

```
blockToolbar: {
  items: [ /* ... */ ],
  icon: 'pilcrow'
  // or
  // icon: '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24">' +
  // '<path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>'
},
toolbar: [ /* ... */ ]

```

You can provide a custom toolbar button icon by [passing an SVG string](#ckeditor5/latest/framework/architecture/ui-library.html--setting-label-icon-and-tooltip).

<a id="ckeditor5/latest/getting-started/setup/toolbar.html--feature-specific-toolbars">

### Feature-specific toolbars

Some features also sport their own dedicated toolbars. In the demos on this page, you can see the [image toolbar](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar) or the [table toolbars](#ckeditor5/latest/features/tables/tables-installation.html--toolbars) when you use the respective features. You will find all information about these toolbars in the [respective feature guides](#ckeditor5/latest/features/index.html).

<a id="ckeditor5/latest/getting-started/setup/ui-language.html">source file: "ckeditor5/latest/getting-started/setup/ui-language.html"</a>

## Setting the UI language

You can change the language of the editor’s UI. On top of 41 fully translated languages (including [38 professional translations](#ckeditor5/latest/getting-started/setup/ui-language.html--list-of-available-professional-translations)), there are many other languages covered by community translators.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--demo">

### Demo

See the demo of the editor in Spanish:

All demos in this guide only present a limited set of features for clarity. Visit the [feature-rich editor example](#ckeditor5/latest/examples/builds-custom/full-featured-editor.html) to see more in action.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--righttoleft-rtl-languages-support">

### Right–to–left (RTL) languages support

CKEditor 5 supports right–to–left languages out–of–the–box. When one of RTL languages is used, the WYSIWYG editor adapts its UI for the best editing experience, for instance, mirroring various elements like toolbars, dropdowns, buttons, etc.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--demo-2">

#### Demo

See the demo of the editor in Arabic:

We are doing our best to deliver the best RTL support to our users and we constantly improve the editor. Check out the [RTL support](https://github.com/ckeditor/ckeditor5/issues/1151) issue on GitHub to learn more and stay up–to–date. Your feedback is much appreciated!

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--loading-additional-languages-from-npm-or-cdn">

### Loading additional languages from npm or CDN

By default, the editor will display in American English. This is the language built into the `ckeditor.js` files. To change the language of the editor UI, you need to load additional language file(s). Check out the following sections to see how to do that:

* [npm](#ckeditor5/latest/getting-started/setup/ui-language.html--npm)
* [CDN](#ckeditor5/latest/getting-started/setup/ui-language.html--cdn)

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--npm">

#### npm

After installing the editor from npm, translations can be imported from `ckeditor5/translations/[lang].js` and must be passed to the editor configuration.

For example, to use Polish, import `'ckeditor5/translations/pl.js'` and pass the translation object to the editor configuration. Please note that if you use premium features, you need to separately import their translations from the proper package.

```
import { ClassicEditor, Essentials, Paragraph, Bold, Italic } from 'ckeditor5';
import { TableOfContents } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [
            Essentials,
            Paragraph,
            Bold,
            Italic,
            TableOfContents
        ],
        toolbar: {
            items: [ 'undo', 'redo', 'bold', 'italic', 'tableOfContents' ]
        },
        translations: [
            coreTranslations,
            premiumFeaturesTranslations
        ]
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

See the [npm installation guide](#ckeditor5/latest/getting-started/installation/self-hosted/quick-start.html--installing-ckeditor-5-using-npm) for more information.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--cdn">

#### CDN

Load translation scripts alongside editor scripts to use the editor with a language different than English. Note that you do not need to pass the translations to the configuration. The editor from CDN will automatically load translations from the attached scripts.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>CKEditor 5 - Quick start CDN</title>

        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css">
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css">
        <!-- Scripts with translations -->
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/translations/es.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/translations/es.umd.js"></script>

        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>
    </head>
    <body>
        <div id="editor"></div>

        <script>
            const { ClassicEditor, Essentials, Paragraph, Bold, Italic } = CKEDITOR;
            const { TableOfContents } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor
                .create( {
                    attachTo: document.querySelector( '#editor' ),
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [
                        Essentials,
                        Paragraph,
                        Bold,
                        Italic
                    ],
                    toolbar: {
                        items: [ 'undo', 'redo', 'bold', 'italic', 'tableOfContents' ]
                    }
                } )
                .then( /* ... */ )
                .catch( /* ... */ );
        </script>
    </body>
</html>

```

See the [CDN installation guide](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-ckeditor-5-from-cdn) for more information.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--setting-the-language-of-the-content">

### Setting the language of the content

In CKEditor 5 you can separately configure the language of the UI and the language of the content. This means you can use the English UI of the editor but type your content in Arabic or Hebrew. The language of the content has an impact on the editing experience, for instance it affects screen readers and spell checkers. It is also particularly useful for typing in certain languages (like [right–to–left](#ckeditor5/latest/getting-started/setup/ui-language.html--righttoleft-rtl-languages-support) ones) because it changes the default alignment of the text.

Configure [config.language](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-language) to change the language of the content. In this example, the UI of the editor will be in English but the content will be in Arabic:

```
ClassicEditor
    .create( {
        // ... Other configuration options ...
        language: {
            // The UI will be English.
            ui: 'en',

            // But the content will be edited in Arabic.
            content: 'ar'
        }
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( err => {
        console.error( err.stack );
    } );

```

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--demo-3">

#### Demo

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--list-of-available-professional-translations">

### List of available professional translations

Below you will find list of available official translations. Each language is accompanied by a code that can be used to set language with the `language:*` setting ([see configuration](../../api/module%5Fcore%5Feditor%5Feditorconfig-LanguageConfig.html)).

| Arabic(ar)          | Bengali(bn)              | Bulgarian(bg)  | Catalan(ca)                   |
| ------------------- | ------------------------ | -------------- | ----------------------------- |
| Chinese (China)(zh) | Chinese (Taiwan)(zh-tw)  | Czech(cs)      | Danish(da)                    |
| Dutch(nl)           | English(American)default | Estonian(et)   | Finnish(fi)                   |
| French(fr)          | German(de)               | Greek(el)      | Hebrew(he)                    |
| Hindi(hi)           | Hungarian(hu)            | Indonesian(id) | Italian(it)                   |
| Japanese(ja)        | Korean(ko)               | Latvian(lv)    | Lithuanian(lt)                |
| Malay(ms)           | Norwegian(no)            | Polish(pl)     | Portuguese (Brazilian)(pt-br) |
| Portuguese(pt)      | Romanian(ro)             | Russian(ru)    | Serbian(sr)                   |
| Slovak(sk)          | Spanish(es)              | Swedish(sv)    | Thai(th)                      |
| Turkish(tr)         | Ukrainian(uk)            | Vietnamese(vi) |                               |

There are community translations available for Australian and British variations of English, too, as well as various others. Language codes for these can be found in the translation files.

<a id="ckeditor5/latest/getting-started/setup/ui-language.html--related-features">

### Related features

Other features that will help you control the content language:

* [Text part Language](#ckeditor5/latest/features/language.html) – Set the language of the selected content part to support multilingual texts.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html">source file: "ckeditor5/latest/getting-started/setup/using-lts-edition.html"</a>

## CKEditor 5 LTS Edition

CKEditor 5 Long-term Support (LTS) Edition provides extended maintenance and support for enterprise customers who require stability and predictable update cycles.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--what-is-lts-edition">

### What is LTS Edition?

CKEditor 5 LTS Edition is for teams that need **long-term stability without sacrificing security**. Released once every two years, each LTS version provides up to 3 years of guaranteed security and compatibility fixes with **zero breaking changes**.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--key-advantages-over-regular-releases">

#### Key advantages over regular releases

| LTS Edition                           | Regular releases                                                                          |
| ------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Once every 2 years**                | Major version every 2–3 months                                                            |
| **3-year security warranty**          | Security fixes only in the latest version                                                 |
| **Third-party API changes assurance** | No third-party compatibility fixes                                                        |
| **Zero breaking changes**             | Minor breaking changes allowed in minor releases;Major breaking changes in major releases |
| **No forced upgrades for 3 years**    | Requires regular major updates                                                            |

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--perfect-for-enterprise-environments">

#### Perfect for enterprise environments

With LTS Edition, you can **stick to a single major version for up to 3 years** without compromising on security or quality. You get:

* **6 months of active development** – New features, enhancements, and bug fixes.
* **2.5 years of maintenance phase** – Security and critical/high third-party compatibility updates (for example, with browsers or Microsoft Word/Excel).
* **Predictable update cycles** – Plan deployments without surprise breaking changes.
* **Focus on your business** – Less time managing editor updates, more time building features.

It means enterprise teams in regulated industries, government, education, or any environment where stability is crucial can deploy once and maintain security without the overhead of frequent major version migrations.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--lts-edition-release-schedule">

### LTS Edition release schedule

Legend:

* **Active phase**: New features and bug fixes. (\~6 months)  
  * In LTS releases: no breaking changes allowed.
  * In Regular releases: minor breaking changes allowed.
* **Maintenance phase**: Security and critical/high third‑party compatibility updates. Available to LTS Edition customers only. (\~2.5 years)

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--schedule-details">

#### Schedule details

Schedule details of the **LTS releases**:

* **Cadence**: One LTS release every 2 years (early October).
* **Current LTS release**: As of October 2025 → **`v47.x`**.
* **Active phase (first 6 months)**: New features and bug fixes; no breaking changes.
* **Maintenance phase (next 2.5 years)**: Security fixes and critical/high-severity third-party compatibility updates (for example, browsers or Microsoft Office). Begins with a technical release that separates the LTS-only distribution.
* **Overlap**: Consecutive LTS releases overlap with each other for 1 year, simplifying migration.
* **Limited breaking changes exception**: A closed, pre‑announced set of new features in an LTS release may introduce minor breaking changes during the Active phase. See the [list of exceptions for v47.x](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--features-excluded-from-the-no-breaking-changes-guarantee-v47x).

Unlike the LTS releases, the Regular releases (for example, `v48.x`, `v49.x`) may include minor breaking changes in minor releases (for example, in `v48.1.0`, `v48.2.0`). Read more in the [Versioning policy](#ckeditor5/latest/updating/versioning-policy.html) guide.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--practical-example">

#### Practical example

Here is how the lifecycle looks for an integrator using the LTS Edition:

1. **Initial installation (October 2025):** The integrator deploys `v47.0.0`.
2. **Active and maintenance phases (2025–2028):**  
  * They may install subsequent **patch releases** (`v47.x.x`) within the same LTS line.
  * These updates include bug fixes, security patches, and critical compatibility adjustments, but **never breaking changes**.
  * Customers are notified whenever a security or compatibility update is available.
3. **Migration window (starting October 2027):**  
  * The next **LTS release**, `v51.x`, becomes available.
  * A **1-year overlap period** begins, giving the integrator flexibility to plan and execute the migration without disruption.
4. **End of support (October 2028):**  
  * The `v47.x` LTS line reaches the end of its 3-year support cycle.
  * From this point onward, the integrator must be on the `v51.x` LTS release (or later) to continue receiving updates.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--features-excluded-from-the-no-breaking-changes-guarantee-v47x">

#### Features excluded from the “no breaking changes” guarantee (v47.x)

Due to the rapid development of the [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html) feature (released in October 2025), during the Active phase of `v47.x`, new releases may include minor breaking changes in this feature. No breaking changes will be allowed for this feature in the Maintenance phase (after April 2026).

The [CKEditor 5 AI Assistant](#ckeditor5/latest/features/ai/ai-assistant/ai-assistant-overview.html) feature (introduced in `v40.0.0`) is not affected by this exception.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--experimental-flags-and-plugins">

#### Experimental flags and plugins

Throughout the life cycle of the LTE version, some experimental features may be added during the Active LTS phase. These can take the form of experimental flags or separate plugins. They would typically be added to test changes coming in the next major release.

Experimental plugins will be marked by a name, for example, `PasteFromMarkdownExperimental`. The feature guide in our documentation will, too, mention if a feature is experimental. It will also inform the user why or what the current issues with the plugin are.

Experimental flag is a [configuration option](../../api/module%5Fengine%5Fengineconfig-ExperimentalFlagsConfig.html) that enables specific features. These are turned off by default and need to be explicitly set to `true` to use. Each experimental feature has its own separate key.

However, these experimental additions are not covered by LTS guarantees, meaning they may change, evolve, or be removed without the stability or compatibility assurances provided for core LTS features.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--installing-the-lts-edition">

### Installing the LTS Edition

The LTS Edition releases of CKEditor 5 are available through standard distribution channels: npm, ZIP, and CDN. Using the editor versions released in the Maintenance phase requires a subscription, which includes the CKEditor 5 LTS Edition add-on. [Contact sales](https://ckeditor.com/contact-sales/) to learn more.

To install an LTS version:

* Choose the latest release of CKEditor 5 in the current LTS line. Starting October 2025, this is the newest version in the `v47.x.x` line.
* Choose a compatible version of the React, Angular, or Vue integrations (if you use one). See the [Compatibility](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility) section below.
* Choose a compatible version of CKBox (if you use it). See the [Compatibility](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility) section below.

Apart from making sure to use the right versions of all dependencies, follow the instructions below.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--npm">

#### npm

When installing CKEditor 5 LTS Edition from npm, make sure to specify the major version like this:

```
npm install ckeditor5@47
npm install ckeditor5-premium-features@47

```

These commands will install the latest version in the `v47.x.x` line.

Apart from this, follow the matching guides covering the technology of your choice (for example, React, Angular, Vue, or vanilla JS) in the [Getting started](#ckeditor5/latest/getting-started/index.html) section.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--zip">

#### ZIP

When installing CKEditor 5 LTS Edition from ZIP, make sure to choose the LTS version:

* [Download ZIP: CKEditor 5 LTS version](https://cdn.ckeditor.com/ckeditor5/47.7.0/zip/ckeditor5-47.7.0.zip)
* [Download ZIP: CKEditor 5 with Premium features LTS version](https://cdn.ckeditor.com/ckeditor5-premium-features/47.7.0/zip/ckeditor5-premium-features-47.7.0.zip)

Apart from this, follow the matching guides covering the technology of your choice (for example, React, Angular, Vue, or vanilla JS) in the [Getting started](#ckeditor5/latest/getting-started/index.html) section.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--cdn">

#### CDN

When installing CKEditor 5 LTS Edition from CDN, make sure to choose the LTS version:

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/47.7.0/ckeditor5.css" />
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/47.7.0/ckeditor5-premium-features.css" />

<script src="https://cdn.ckeditor.com/ckeditor5/47.7.0/ckeditor5.umd.js"></script>
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/47.7.0/ckeditor5-premium-features.umd.js"></script>

```

Or specify `version: '47.7.0'` when using functions such as [useCKEditorCloud()](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html).

Apart from this, follow the matching guides covering the technology of your choice (for example, React, Angular, Vue, or vanilla JS) in the [Getting started](#ckeditor5/latest/getting-started/index.html) section.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--online-builder">

#### Online Builder

CKEditor 5 LTS Edition also has it own version of Online Builder. Same as its standard version it offers an easy-to-use user interface to help you configure, preview, and download the editor suited to your needs.

[Check out our interactive Builder for LTS Edition.](https://ckeditor.com/ckeditor-5/builder/lts-v47/)

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--dedicated-documentation">

### Dedicated documentation

Since our software constantly evolves there may be some discrepancies between the latest version of CKEditor 5 and its LTS Edition.

When it comes to using LTS edition, please refer to the [dedicated LTS Documentation branch](https://ckeditor.com/docs/ckeditor5/lts-v47/index.html).

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--lts-additional-warranties">

### LTS additional warranties

The LTS Edition comes with extended guarantees beyond regular release policies, designed to give enterprise teams stability and peace of mind.

Please note that time limitations apply to all warranties described in this section.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--3-year-security-warranty">

#### 3-year security warranty

Throughout the Active and Maintenance phases (a total of 3 years), the LTS release will receive security fixes for any detected vulnerabilities.

If dependency has a vulnerability and provides a patch, CKEditor 5 will ship a new LTS patch release.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--third-party-api-changes-assurance">

#### Third-party API changes assurance

Third-party APIs include:

* Officially supported frameworks (React, Angular, Vue).
* Supported browsers, mobile environments, and operating systems.
* Microsoft Word/Excel and Google Docs.

The LTS Edition ensures fixes for **critical or high-severity regressions** caused by changes in these third-party products.

* Fixes are delivered throughout the 3-year Active and Maintenance phases.
* Exceptions apply if regressions cannot be resolved on the CKEditor side (for example, if they require fixes from the third-party vendor).

In short, CKEditor 5 LTS aims to ensure the integration quality remains stable during the entire 3-year support window.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility">

### Compatibility

This section outlines compatibility rules and guarantees specific to the LTS Edition.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-with-ckeditor-cloud-services">

#### Compatibility with CKEditor Cloud Services

The cloud-hosted CKEditor Cloud Services support CKEditor 5 versions **up to 5 years old**, which includes all currently supported LTS releases.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-with-ckeditor-cloud-services-on-premises">

#### Compatibility with CKEditor Cloud Services On-Premises

The latest On-Premises CKEditor Cloud Services support CKEditor 5 versions **up to 5 years old**, covering all active LTS releases.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-with-browser-versions-operating-systems-and-other-third-party-apissoftware-products">

#### Compatibility with browser versions, operating systems, and other third-party APIs/software products

The CKEditor 5 LTS Edition follows the same compatibility guarantees as regular releases, with the added benefit of **extended maintenance**:

* **Supported environments:** All browsers, operating systems, and mobile platforms officially listed in the [Browser compatibility](#ckeditor5/latest/support/browser-compatibility.html) guide.
* **Assurance period:** Critical/high-severity regressions caused by updates in these environments will be fixed for the full 3-year LTS lifecycle. See [Third-party API changes assurance](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--3-year-security-warranty) for details.

It ensures that CKEditor 5 remains stable and reliable in evolving ecosystems, while minimizing disruption in long-term projects.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-with-react-angular-and-vue-versions">

#### Compatibility with React, Angular, and Vue versions

The LTS Edition ensures predictable integration with major JavaScript frameworks used in enterprise applications.

* **Framework coverage:** Each LTS release supports the versions of React, Angular, and Vue that were officially listed as supported on the day the LTS release was published.
* **Ongoing support:** In addition, all new versions of these frameworks released during the 3-year LTS support period will also be supported.
* **Support window:** It means your project can safely adopt both the originally supported framework versions and any new framework releases that appear during the lifecycle of the LTS line.
* **Updates:** Compatibility fixes will be provided if critical or high-severity regressions appear in any of the covered framework versions.

For details on which framework versions are supported by a given LTS line, see the [Compatibility matrix](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-matrix) below.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-with-add-ons-delivered-by-ckeditors-partners">

#### Compatibility with add-ons delivered by CKEditor’s partners

CKEditor integrates with several add-ons delivered by trusted partners, including:

* **Spell and grammar checker** by _WebSpellChecker_.
* **Math equations and Chemical formulas** by _Wiris_.
* **Image optimizer** by _Uploadcare_.

Please note that the **LTS Edition does not guarantee ongoing compatibility with these third-party services**.

If your project depends on any of these integrations, we recommend [contacting us](https://ckeditor.com/contact-sales/) to discuss available options and support arrangements.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-matrix">

#### Compatibility matrix

When installing CKEditor 5 LTS Edition, ensure you use the compatible versions of other products from the CKEditor Ecosystem.

Refer to the table below to see which versions of each ecosystem library should be used together with CKEditor 5 LTS Edition.

| Software | Supported versions | Notes                                                                                                                |
| -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| React    | \>=16.13.1         | Use with [@ckeditor/ckeditor5-react](https://www.npmjs.com/package/@ckeditor/ckeditor5-react) in version ^11.0.0     |
| Angular  | \>=16.0.0          | Use with [@ckeditor/ckeditor5-angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular) in version ^10.0.0 |
| Vue      | \>=3.0.0           | Use with [@ckeditor/ckeditor5-vue](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue) in version ^7.3.0          |
| CKBox    | \>=2.8.2           |                                                                                                                      |

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--faq">

### FAQ

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--what-is-the-current-ckeditor-5-lts-version">

#### What is the current CKEditor 5 LTS version?

The current LTS version line is `v47.x`.

The latest release in this line is `v47.7.0`.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--will-i-need-to-upgrade-ckeditor-5-if-i-use-the-lts-edition">

#### Will I need to upgrade CKEditor 5 if I use the LTS Edition?

No major upgrades are required for 3 years, unless you choose to adopt a newer version earlier.

We do recommend installing patch releases within the LTS line, as they may include stability improvements or security fixes. These updates never introduce breaking changes. They are safe and easy to adopt.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--can-i-switch-from-a-regular-release-to-the-lts-edition-later">

#### Can I switch from a regular release to the LTS Edition later?

Yes. You can switch to the LTS Edition at any time, though adopting it early maximizes your stability window.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--can-i-switch-from-the-lts-edition-to-a-regular-release">

#### Can I switch from the LTS Edition to a regular release?

Yes. You can switch to a regular release whenever you want (for example, to access a new feature). Once the next LTS release is published, you can return to the LTS line.

Remember that while on a regular release, you lose the additional warranties offered by the LTS Edition.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--what-happens-after-the-3-year-lts-support-period-ends">

#### What happens after the 3-year LTS support period ends?

You can either upgrade to the next LTS release or move to the latest regular release.

To ensure a seamless transition, each LTS release overlaps with the next for a period of one year.

<a id="ckeditor5/latest/getting-started/setup/using-lts-edition.html--i-need-additional-custom-guarantees-or-services-what-should-i-do">

#### I need additional custom guarantees or services. What should I do?

CKEditor offers enterprise-grade services, including SLAs, custom development, and dedicated support.

[Contact our sales team](https://ckeditor.com/contact-sales/) to discuss your needs.

<a id="ckeditor5/latest/index.html">source file: "ckeditor5/latest/index.html"</a>

## CKEditor 5 documentation

[Getting started](#ckeditor5/latest/getting-started/index.html)

Learn how to install, integrate and configure CKEditor 5\. More complex aspects, like using frameworks or styling your editor and content are explained here, too.

[Features](#ckeditor5/latest/features/index.html)

Learn about the plethora of features available for CKEditor 5 for editing, productivity, collaboration and more!

[Examples](#ckeditor5/latest/examples/index.html)

Try out CKEditor 5\. See some of the possible customizations of CKEditor.

[CKEditor 5 Framework](#ckeditor5/latest/framework/index.html)

Learn how to work with CKEditor 5 Framework, customize it, create your own plugins and custom editors, change the UI or even bring your own UI to the editor.

[API Reference](api/index.html)

The complete API documentation.

[Updating and maintaining](#ckeditor5/latest/updating/index.html)

Find out all about updating to the newest version, dealing with breaking changes, and other important information on how to maintain your CKEditor 5\. This section also covers migrating from CKEditor 4.

[Support](#ckeditor5/latest/support/index.html)

Need help with CKEditor 5? Learn how to get support and find answers to the most frequently asked questions!

<a id="ckeditor5/latest/index.html--contribute">

### Contribute

CKEditor 5 is an Open Source project and your contribution is most welcome. Feel free to [report bugs](#ckeditor5/latest/support/index.html--reporting-issues) or improve the code on [GitHub](https://github.com/ckeditor/ckeditor5). Since CKEditor 5 is localized, you can also help [translating it](#ckeditor5/latest/framework/contributing/contributing.html--translating). You do not need to be a programmer to contribute to the project!

<a id="ckeditor5/latest/snippets/examples/bootstrap-ui.html">source file: "ckeditor5/latest/snippets/examples/bootstrap-ui.html"</a>

<a id="ckeditor5/latest/snippets/examples/bootstrap-ui.html--editor">

### Custom UI

This editor uses **Bootstrap** components to build the user interface.

<a id="ckeditor5/latest/support/browser-compatibility.html">source file: "ckeditor5/latest/support/browser-compatibility.html"</a>

## Browser compatibility

<a id="ckeditor5/latest/support/browser-compatibility.html--desktop-environment">

### Desktop environment

CKEditor 5 is currently supported in the following desktop browsers:

* Full support:  
  * Chrome (latest stable release).
  * Firefox (latest stable release).
  * Safari (latest stable release).
  * Opera (latest stable release).
  * Electron (latest stable release).
  * Edge (latest stable release).

<a id="ckeditor5/latest/support/browser-compatibility.html--mobile-environment">

### Mobile environment

CKEditor 5 is currently supported in the following mobile environments:

* Android (all vendor-supported versions)
* iOS (all vendor-supported versions)
* Android WebView
* iOS WebView (UIWebView and WKWebView)

<a id="ckeditor5/latest/support/browser-compatibility.html--quality-assurance">

### Quality assurance

To ensure the highest quality, we maintain a complete test suite with a stable 100% of code coverage for each of the packages. As of May 2022, this means over 21,000 tests and the number is growing – you can check the [Why CKEditor?](https://ckeditor.com/why-ckeditor/) page if you want more statistics about CKEditor!

Such an extensive test suite requires a proper continuous integration service. We use [Travis CI](https://travis-ci.com/) as a build platform. This service ensures seamless and fast developer experience and allow us to focus on the job.

<a id="ckeditor5/latest/support/error-codes.html">source file: "ckeditor5/latest/support/error-codes.html"</a>

## Error codes

CKEditor 5 Framework logs errors and warnings to the console. The following list contains more detailed descriptions of those issues.

* <a id="ckeditor5/latest/support/error-codes.html--error-accessibility-unknown-keystroke-info-category">  
####  
`[accessibility-unknown-keystroke-info-category](#ckeditor5/latest/support/error-codes.html--error-accessibility-unknown-keystroke-info-category)`  
Cannot add keystrokes in an unknown category. Use [addKeystrokeInfoCategory](../api/module%5Fcore%5Faccessibility-Accessibility.html#function-addKeystrokeInfoCategory)to add a new category or make sure the specified category exists.  
##### Parameters  
`categoryId : string`  
The id of the unknown keystroke category.  
`keystrokes : [AddKeystrokeInfosData#keystrokes](../api/module%5Fcore%5Faccessibility-AddKeystrokeInfosData.html#member-keystrokes)`  
Keystroke definitions about to be added.
* <a id="ckeditor5/latest/support/error-codes.html--error-accessibility-unknown-keystroke-info-group">  
####  
`[accessibility-unknown-keystroke-info-group](#ckeditor5/latest/support/error-codes.html--error-accessibility-unknown-keystroke-info-group)`  
Cannot add keystrokes to an unknown group.  
Use [addKeystrokeInfoGroup](../api/module%5Fcore%5Faccessibility-Accessibility.html#function-addKeystrokeInfoGroup)to add a new group or make sure the specified group exists.  
##### Parameters  
`groupId : string`  
The id of the unknown keystroke group.  
`categoryId : string`  
The id of category the unknown group should belong to.  
`keystrokes : [AddKeystrokeInfosData#keystrokes](../api/module%5Fcore%5Faccessibility-AddKeystrokeInfosData.html#member-keystrokes)`  
Keystroke definitions about to be added.
* <a id="ckeditor5/latest/support/error-codes.html--error-addcommentthreadcommand-incorrect-ranges">  
####  
`[addcommentthreadcommand-incorrect-ranges](#ckeditor5/latest/support/error-codes.html--error-addcommentthreadcommand-incorrect-ranges)`  
Cannot add comment thread. Selection is empty and no valid ranges provided.
* <a id="ckeditor5/latest/support/error-codes.html--error-addcommentthreadcommand-user-not-found">  
####  
`[addcommentthreadcommand-user-not-found](#ckeditor5/latest/support/error-codes.html--error-addcommentthreadcommand-user-not-found)`  
Cannot add comment thread. User is not defined.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-aws-adapter-not-supported">  
####  
`[ai-aws-adapter-not-supported](#ckeditor5/latest/support/error-codes.html--error-ai-aws-adapter-not-supported)`  
The `AWSTextAdapter` is no longer supported. The Amazon Bedrock adapter has been removed. Please contact CKEditor support at https://support.ckeditor.com for more information about available AI adapters.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-content-too-large">  
####  
`[ai-chat-content-too-large](#ckeditor5/latest/support/error-codes.html--error-ai-chat-content-too-large)`  
The content is too large to be used as chat context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-file-too-large">  
####  
`[ai-chat-context-file-too-large](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-file-too-large)`  
The file is too large to be used as chat context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-file-too-many-pages">  
####  
`[ai-chat-context-file-too-many-pages](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-file-too-many-pages)`  
The file has too many pages to be used as chat context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-form-data-size-limits-exceeded">  
####  
`[ai-chat-context-form-data-size-limits-exceeded](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-form-data-size-limits-exceeded)`  
The form data size limits have been exceeded for chat context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-invalid-data">  
####  
`[ai-chat-context-invalid-data](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-invalid-data)`  
An error thrown when a URL resource has invalid data type (not a string).  
##### Parameters  
`resourceId : string`  
The ID of the resource.  
`sourceId : string`  
The ID of the source provider.  
`expectedType : string`  
The expected data type.  
`actualType : string`  
The actual data type.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-unsupported-file-type">  
####  
`[ai-chat-context-unsupported-file-type](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-unsupported-file-type)`  
The file type is not supported for chat context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-context-unsupported-type">  
####  
`[ai-chat-context-unsupported-type](#ckeditor5/latest/support/error-codes.html--error-ai-chat-context-unsupported-type)`  
An error thrown when an unsupported resource type is used. Only URL and FILE types are supported.  
##### Parameters  
`resourceId : string`  
The ID of the resource.  
`sourceId : string`  
The ID of the source provider.  
`resourceType : string`  
The unsupported resource type.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-controller-no-active-conversation">  
####  
`[ai-chat-controller-no-active-conversation](#ckeditor5/latest/support/error-codes.html--error-ai-chat-controller-no-active-conversation)`  
User message was sent before the conversation was started.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-already-started">  
####  
`[ai-chat-conversation-already-started](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-already-started)`  
An error thrown when trying to start a conversation that is already started.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-init-failed">  
####  
`[ai-chat-conversation-init-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-init-failed)`  
An error thrown when the conversation fails to initialize (e.g. due to a network error).
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-init-from-id-failed">  
####  
`[ai-chat-conversation-init-from-id-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-init-from-id-failed)`  
An error thrown when the conversation fails to initialize from ID (e.g. due to a network error).
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-not-found">  
####  
`[ai-chat-conversation-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-not-found)`  
An error thrown when the conversation conversation with given ID was not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-set-model-not-available">  
####  
`[ai-chat-conversation-set-model-not-available](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-set-model-not-available)`  
An error thrown when trying to set model that is not available.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-set-model-null">  
####  
`[ai-chat-conversation-set-model-null](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-set-model-null)`  
An error thrown when trying to set model to null.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-start-failed">  
####  
`[ai-chat-conversation-start-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-start-failed)`  
An error thrown when the conversation fails to start (e.g. due to a network error).
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-start-no-model-selected">  
####  
`[ai-chat-conversation-start-no-model-selected](#ckeditor5/latest/support/error-codes.html--error-ai-chat-conversation-start-no-model-selected)`  
An error thrown when trying to start a conversation but no model is selected.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-default-model-id-unrecognized">  
####  
`[ai-chat-default-model-id-unrecognized](#ckeditor5/latest/support/error-codes.html--error-ai-chat-default-model-id-unrecognized)`  
Model with given ID configured via `ai.models.defaultModelId` is not available. Falling back to the first available model.  
##### Parameters  
`defaultModelId : string`  
The ID of the model configured via `ai.models.defaultModelId` that was not found.  
`fallBackModelId : string`  
The ID of the fall back model
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-document-upload-failed">  
####  
`[ai-chat-document-upload-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-document-upload-failed)`  
An error thrown when the document fails to upload as AI chat context (e.g. due to a network error).
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-reply-item">  
####  
`[ai-chat-feed-view-item-not-a-reply-item](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-reply-item)`  
Item with the given ID cannot be updated because it is not a reply item.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-suggestion-item">  
####  
`[ai-chat-feed-view-item-not-a-suggestion-item](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-suggestion-item)`  
Item with the given ID cannot be updated because it is not a suggestion item.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-suggestion-or-reply-item">  
####  
`[ai-chat-feed-view-item-not-a-suggestion-or-reply-item](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-a-suggestion-or-reply-item)`  
Item with the given ID cannot be updated because it is not a suggestion or reply item.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-found">  
####  
`[ai-chat-feed-view-item-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-item-not-found)`  
Item with the given ID does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-scroll-to-suggestion-invalid-item">  
####  
`[ai-chat-feed-view-scroll-to-suggestion-invalid-item](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-scroll-to-suggestion-invalid-item)`  
Item with the given ID cannot be scrolled to because it is not a suggestion item.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-scroll-to-suggestion-part-view-not-found">  
####  
`[ai-chat-feed-view-scroll-to-suggestion-part-view-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-feed-view-scroll-to-suggestion-part-view-not-found)`  
Part view with the given index does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-file-upload-failed">  
####  
`[ai-chat-file-upload-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-file-upload-failed)`  
An error thrown when the file fails to upload as AI chat context (e.g. due to a network error).
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-handle-user-conversation-not-initialized">  
####  
`[ai-chat-handle-user-conversation-not-initialized](#ckeditor5/latest/support/error-codes.html--error-ai-chat-handle-user-conversation-not-initialized)`  
An error thrown when trying to handle user message but conversation is not initialized.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-handle-user-interaction-already-in-progress">  
####  
`[ai-chat-handle-user-interaction-already-in-progress](#ckeditor5/latest/support/error-codes.html--error-ai-chat-handle-user-interaction-already-in-progress)`  
An error thrown when trying to handle user message but interaction is already in progress.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-interaction-error">  
####  
`[ai-chat-interaction-error](#ckeditor5/latest/support/error-codes.html--error-ai-chat-interaction-error)`  
An error thrown when error is received from the AI endpoint.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-invalid-request">  
####  
`[ai-chat-invalid-request](#ckeditor5/latest/support/error-codes.html--error-ai-chat-invalid-request)`  
The chat request data is invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-missing-channel-id">  
####  
`[ai-chat-missing-channel-id](#ckeditor5/latest/support/error-codes.html--error-ai-chat-missing-channel-id)`  
The collaboration `channelId` configuration is required for AI conversation management.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-model-already-set">  
####  
`[ai-chat-model-already-set](#ckeditor5/latest/support/error-codes.html--error-ai-chat-model-already-set)`  
The model has already been set and cannot be changed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-model-id-unrecognized">  
####  
`[ai-chat-model-id-unrecognized](#ckeditor5/latest/support/error-codes.html--error-ai-chat-model-id-unrecognized)`  
Model with given ID is not available. Falling back to the default model.  
##### Parameters  
`modelId : string`  
The ID of the model that was not found.  
`fallBackModelId : string`  
The ID of the fall back model.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-model-not-found">  
####  
`[ai-chat-model-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-model-not-found)`  
The requested model was not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-resource-load-failed">  
####  
`[ai-chat-resource-load-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-resource-load-failed)`  
An error thrown when a resource fails to load data (e.g. due to a network error).  
##### Parameters  
`resourceId : string`  
The ID of the resource that failed to load.  
`sourceId : string`  
The ID of the source provider.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-resource-no-data">  
####  
`[ai-chat-resource-no-data](#ckeditor5/latest/support/error-codes.html--error-ai-chat-resource-no-data)`  
An error thrown when a resource has no data available.  
##### Parameters  
`resourceId : string`  
The ID of the resource.  
`sourceId : string`  
The ID of the source provider.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-ai-tabs-not-found">  
####  
`[ai-chat-shortcuts-ai-tabs-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-ai-tabs-not-found)`  
The [AI Chat Shortcuts](../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcuts.html) feature was unable to switch the user interface because the [AI Tabs](../api/module%5Fai%5Faitabs%5Faitabs-AITabs.html) plugin was not found.  
Please make sure the AI Tabs feature is enabled before running shortcuts that interact with it.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-invalid-config">  
####  
`[ai-chat-shortcuts-invalid-config](#ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-invalid-config)`  
The [AI Chat Shortcuts](../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcuts.html) configuration is invalid. Please make sure the shortcut has all necessary properties.  
See [AIChatShortcutChatDefinition](../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcutChatDefinition.html) to learn more about configuring chat shortcuts.  
##### Parameters  
`shortcut : object`  
The chat shortcut configuration that is invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-review-mode-not-found">  
####  
`[ai-chat-shortcuts-review-mode-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-review-mode-not-found)`  
The [AI Chat Shortcuts](../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcuts.html) feature was unable to run the shortcut because the [AI Review Mode](../api/module%5Fai%5Faireviewmode%5Faireviewmode-AIReviewMode.html) feature was not found.  
Please make sure the AI Review mode feature is enabled before running shortcuts that interact with it.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-translate-not-found">  
####  
`[ai-chat-shortcuts-translate-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-shortcuts-translate-not-found)`  
The [AI Chat Shortcuts](../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcuts.html) feature was unable to run the shortcut because the [AI Translate](../api/module%5Fai%5Faitranslate%5Faitranslate-AITranslate.html) feature was not found.  
Please make sure the AI Translate feature is enabled before running shortcuts that interact with it.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-source-not-found">  
####  
`[ai-chat-source-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-chat-source-not-found)`  
An error thrown when a source provider is not found.  
##### Parameters  
`sourceId : string`  
The ID of the source provider.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-source-resources-load-failed">  
####  
`[ai-chat-source-resources-load-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-source-resources-load-failed)`  
An error thrown when resources fail to load from a source provider.  
##### Parameters  
`sourceId : string`  
The ID of the source provider.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-unsafe-content-detected">  
####  
`[ai-chat-unsafe-content-detected](#ckeditor5/latest/support/error-codes.html--error-ai-chat-unsafe-content-detected)`  
Unsafe content was detected in the chat request.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-unsupported-content-type">  
####  
`[ai-chat-unsupported-content-type](#ckeditor5/latest/support/error-codes.html--error-ai-chat-unsupported-content-type)`  
The content type is not supported for chat operations.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-chat-url-upload-failed">  
####  
`[ai-chat-url-upload-failed](#ckeditor5/latest/support/error-codes.html--error-ai-chat-url-upload-failed)`  
An error thrown when the URL fails to upload (e.g. due to a network error).  
##### Parameters  
`url : string`  
The URL that failed to upload.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-commands-config-order-collision">  
####  
`[ai-commands-config-order-collision](#ckeditor5/latest/support/error-codes.html--error-ai-commands-config-order-collision)`  
The same `order` value has been set for two (or more) definitions in the AI Assistant feature configuration.  
Learn more about [command definitions](../api/module%5Fai%5Faiassistant%5Faiassistant-AICommandDefinition.html) and [group definitions](../api/module%5Fai%5Faiassistant%5Faiassistant-AIGroupDefinition.html) used in the [feature configuration](../api/module%5Fai%5Faiassistant%5Faiassistant-AIAssistantConfig.html#member-commands)  
##### Parameters  
`conflictingDefinitions : Array<never>`  
Definitions that have the same `order` value.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-documentposition-createfrompath-path-cannot-be-empty">  
####  
`[ai-documentposition-createfrompath-path-cannot-be-empty](#ckeditor5/latest/support/error-codes.html--error-ai-documentposition-createfrompath-path-cannot-be-empty)`  
The path cannot be empty when creating document position from path.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-documentposition-index-out-of-bounds">  
####  
`[ai-documentposition-index-out-of-bounds](#ckeditor5/latest/support/error-codes.html--error-ai-documentposition-index-out-of-bounds)`  
The index is out of bounds for the document position.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-get-editor-from-context-no-editor">  
####  
`[ai-get-editor-from-context-no-editor](#ckeditor5/latest/support/error-codes.html--error-ai-get-editor-from-context-no-editor)`  
No editor found in the context.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-interaction-invalid-event-type">  
####  
`[ai-interaction-invalid-event-type](#ckeditor5/latest/support/error-codes.html--error-ai-interaction-invalid-event-type)`  
There was a problem processing the response chunk. The event type is invalid.  
##### Parameters  
`chunk : object`  
The chunk that was received from the AI endpoint.  
`event : string`  
The event type that was received from the AI endpoint.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-invalid-content-type">  
####  
`[ai-invalid-content-type](#ckeditor5/latest/support/error-codes.html--error-ai-invalid-content-type)`  
The content type provided is invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-invalid-license-key">  
####  
`[ai-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-ai-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-missing-token">  
####  
`[ai-missing-token](#ckeditor5/latest/support/error-codes.html--error-ai-missing-token)`  
The authentication [config.cloudServices.tokenUrl](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl)configuration is required for handling AI connection.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-models-unable-to-retrieve">  
####  
`[ai-models-unable-to-retrieve](#ckeditor5/latest/support/error-codes.html--error-ai-models-unable-to-retrieve)`  
The editor was unable to retrieve the list of available AI models. This can happen due to a network error.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-no-track-changes">  
####  
`[ai-no-track-changes](#ckeditor5/latest/support/error-codes.html--error-ai-no-track-changes)`  
Tried to insert AI-proposed changes as suggestions but track changes plugin is not loaded.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-models-unable-to-retrieve">  
####  
`[ai-quick-actions-models-unable-to-retrieve](#ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-models-unable-to-retrieve)`  
The editor was unable to retrieve the list of available AI models. This can happen due to a network error. Some quick actions may be unavailable or work improperly.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-plugin-not-found">  
####  
`[ai-quick-actions-plugin-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-plugin-not-found)`  
Thrown when trying to execute an AI Quick Action but the required plugin is not available. This error indicates that the required plugin is not installed or not loaded.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-unavailable-model">  
####  
`[ai-quick-actions-unavailable-model](#ckeditor5/latest/support/error-codes.html--error-ai-quick-actions-unavailable-model)`  
A quick action is using an outdated or unavailable model in its configuration. The quick action has been disabled. Please update the model to a supported version.  
##### Parameters  
`actionId : string`  
The ID of the quick action with the outdated model.  
`modelId : string`  
The outdated model identifier.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-rate-limits-exceeded">  
####  
`[ai-rate-limits-exceeded](#ckeditor5/latest/support/error-codes.html--error-ai-rate-limits-exceeded)`  
Rate limits for the AI service have been exceeded.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-reply-get-content-parts-group-not-found">  
####  
`[ai-reply-get-content-parts-group-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-reply-get-content-parts-group-not-found)`  
The change group with the given index does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-request-aborted">  
####  
`[ai-request-aborted](#ckeditor5/latest/support/error-codes.html--error-ai-request-aborted)`  
Request to the AI API was aborted.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-request-failed">  
####  
`[ai-request-failed](#ckeditor5/latest/support/error-codes.html--error-ai-request-failed)`  
Failed to fetch response from the AI API.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-response-parser-unable-to-set-up-parser">  
####  
`[ai-response-parser-unable-to-set-up-parser](#ckeditor5/latest/support/error-codes.html--error-ai-response-parser-unable-to-set-up-parser)`  
The Markdown to HTML converter was unable to set up the parser.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-chunk-error">  
####  
`[ai-review-mode-check-run-chunk-error](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-chunk-error)`  
An error specific to one chunk occurred during the AI review mode check run.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-failed">  
####  
`[ai-review-mode-check-run-failed](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-failed)`  
The current check run has failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-general-error">  
####  
`[ai-review-mode-check-run-general-error](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-check-run-general-error)`  
A general error occurred during the AI review mode check run.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-command-unavailable-due-to-missing-model">  
####  
`[ai-review-mode-command-unavailable-due-to-missing-model](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-command-unavailable-due-to-missing-model)`  
A review command is unavailable because the required AI model is not available.  
This can happen, for example, due to a network error that prevents fetching the list of available models or if the model is no longer available. The command will not be visible in the UI and cannot be executed.  
See [AIModelsConfig](../api/module%5Fai%5Faicore%5Fmodel%5Faimodels-AIModelsConfig.html) documentation for more details on AI models configuration.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-models-unable-to-retrieve">  
####  
`[ai-review-mode-models-unable-to-retrieve](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-models-unable-to-retrieve)`  
The editor was unable to retrieve the list of available AI models for review mode for a custom command. This can happen, for example, due to a network error.  
If this error occurs, review custom command will not be available.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-no-current-check-run">  
####  
`[ai-review-mode-no-current-check-run](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-no-current-check-run)`  
The current check run was not started or has been removed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-non-existent-commands-used">  
####  
`[ai-review-mode-non-existent-commands-used](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-non-existent-commands-used)`  
Non-existent command IDs were used to configure AI Review commands list.  
See [availableCommands](../api/module%5Fai%5Faireviewmode%5Faireviewmode-AIReviewModeConfig.html#member-availableCommands) documentation.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-review-mode-source-check-not-found">  
####  
`[ai-review-mode-source-check-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-review-mode-source-check-not-found)`  
The source check with the given ID was not loaded or has been removed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-tabs-configuration-not-found">  
####  
`[ai-tabs-configuration-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-tabs-configuration-not-found)`  
Configuration for the AI tabs container was not found.  
Please make sure that `config.ai.container` is set.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-tabs-sidebar-container-element-not-found">  
####  
`[ai-tabs-sidebar-container-element-not-found](#ckeditor5/latest/support/error-codes.html--error-ai-tabs-sidebar-container-element-not-found)`  
AI tabs were configured in the `'sidebar'` mode but the `config.ai.container.element` was not set.  
Please make sure that `config.ai.container.element` refers to an existing element in the DOM.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-tabs-unsupported-ui-side">  
####  
`[ai-tabs-unsupported-ui-side](#ckeditor5/latest/support/error-codes.html--error-ai-tabs-unsupported-ui-side)`  
Target side is not supported.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-tabs-unsupported-ui-type">  
####  
`[ai-tabs-unsupported-ui-type](#ckeditor5/latest/support/error-codes.html--error-ai-tabs-unsupported-ui-type)`  
Target UI type is not supported.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-trial-license-key-reached-limit-changes">  
####  
`[ai-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-ai-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-ai-usage-limits-exceeded">  
####  
`[ai-usage-limits-exceeded](#ckeditor5/latest/support/error-codes.html--error-ai-usage-limits-exceeded)`  
Usage limits for the AI service have been exceeded.
* <a id="ckeditor5/latest/support/error-codes.html--error-aiadapter-text-adapter-not-set">  
####  
`[aiadapter-text-adapter-not-set](#ckeditor5/latest/support/error-codes.html--error-aiadapter-text-adapter-not-set)`  
AI text adapter plugin has not been added to the editor. Use one of the provided adapter plugins (e.g. `OpenAITextAdapter`if you connect to OpenAI or Azure OpenAI service) or create a custom adapter.
* <a id="ckeditor5/latest/support/error-codes.html--error-aitextadapter-send-request-failed">  
####  
`[aitextadapter-send-request-failed](#ckeditor5/latest/support/error-codes.html--error-aitextadapter-send-request-failed)`  
Sending a request to the AI service API failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-alignment-config-classname-already-defined">  
####  
`[alignment-config-classname-already-defined](#ckeditor5/latest/support/error-codes.html--error-alignment-config-classname-already-defined)`  
The same `className` in one of the `alignment.options` was already declared.  
##### Parameters  
`option : object`  
First option that declares given `className`.  
`configuredOptions : object`

  * Contents of `alignment.options`.
* <a id="ckeditor5/latest/support/error-codes.html--error-alignment-config-classnames-are-missing">  
####  
`[alignment-config-classnames-are-missing](#ckeditor5/latest/support/error-codes.html--error-alignment-config-classnames-are-missing)`  
The `className` property has to be defined for all options once at least one option declares `className`.  
##### Parameters  
`configuredOptions : object`  
Contents of `alignment.options`.
* <a id="ckeditor5/latest/support/error-codes.html--error-alignment-config-name-already-defined">  
####  
`[alignment-config-name-already-defined](#ckeditor5/latest/support/error-codes.html--error-alignment-config-name-already-defined)`  
The same `name` in one of the `alignment.options` was already declared. Each `name` representing one alignment option can be set exactly once.  
##### Parameters  
`option : object`  
First option that declares given `name`.  
`configuredOptions : object`  
Contents of `alignment.options`.
* <a id="ckeditor5/latest/support/error-codes.html--error-alignment-config-name-not-recognized">  
####  
`[alignment-config-name-not-recognized](#ckeditor5/latest/support/error-codes.html--error-alignment-config-name-not-recognized)`  
The `name` in one of the `alignment.options` is not recognized. The available options are: `'left'`, `'right'`, `'center'` and `'justify'`.  
##### Parameters  
`option : object`  
Options with unknown value of the `name` property.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotation-invalid-target">  
####  
`[annotation-invalid-target](#ckeditor5/latest/support/error-codes.html--error-annotation-invalid-target)`  
An error thrown when the target type is invalid.  
The target should be either:

  * a DOM element or an array of DOM elements,
  * or [a rect instance](../api/module%5Futils%5Fdom%5Frect-Rect.html),
  * or `null`,
  * or a callback that returns one of the above.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationcollection-duplicated-item">  
####  
`[annotationcollection-duplicated-item](#ckeditor5/latest/support/error-codes.html--error-annotationcollection-duplicated-item)`  
The annotation already exists in the collection. It cannot be added more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationcollection-not-existing-item">  
####  
`[annotationcollection-not-existing-item](#ckeditor5/latest/support/error-codes.html--error-annotationcollection-not-existing-item)`  
The annotation does not exist in the collection and cannot be removed.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-annotation-mismatch">  
####  
`[annotationsuis-annotation-mismatch](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-annotation-mismatch)`  
An annotation should always belong only to one annotations UI instance. Check filters that were passed to [activate methods](../api/module%5Fcomments%5Fannotations%5Fannotationsuis-AnnotationsUIs.html#function-activate).
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui">  
####  
`[annotationsuis-missing-ui](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui)`  
UI with a given name has been not registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui">  
####  
`[annotationsuis-missing-ui](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui)`  
UI with a given name has been not registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui">  
####  
`[annotationsuis-missing-ui](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-missing-ui)`  
UI with a given name has been not registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-register-already-registered">  
####  
`[annotationsuis-register-already-registered](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-register-already-registered)`  
UI with a given name already registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-annotationsuis-register-invalid-interface">  
####  
`[annotationsuis-register-invalid-interface](#ckeditor5/latest/support/error-codes.html--error-annotationsuis-register-invalid-interface)`  
The annotations UI plugin should implement `AnnotationsUI` interface.
* <a id="ckeditor5/latest/support/error-codes.html--error-attachtoform-missing-elementapi-interface">  
####  
`[attachtoform-missing-elementapi-interface](#ckeditor5/latest/support/error-codes.html--error-attachtoform-missing-elementapi-interface)`  
The editor passed to `attachToForm()` must implement the [ElementApi](../api/module%5Fcore%5Feditor%5Futils%5Felementapimixin-ElementApi.html) interface.
* <a id="ckeditor5/latest/support/error-codes.html--error-attribute-element-get-elements-with-same-id-no-id">  
####  
`[attribute-element-get-elements-with-same-id-no-id](#ckeditor5/latest/support/error-codes.html--error-attribute-element-get-elements-with-same-id-no-id)`  
Cannot get elements with the same id for an attribute element without id.
* <a id="ckeditor5/latest/support/error-codes.html--error-attribute-operation-attribute-exists">  
####  
`[attribute-operation-attribute-exists](#ckeditor5/latest/support/error-codes.html--error-attribute-operation-attribute-exists)`  
The attribute with given key already exists for the given node.  
##### Parameters  
`root : [ModelItem](../api/module%5Fengine%5Fmodel%5Fitem-ModelItem.html)`  
The item element.  
`key : string`  
The key of the attribute.
* <a id="ckeditor5/latest/support/error-codes.html--error-attribute-operation-range-not-flat">  
####  
`[attribute-operation-range-not-flat](#ckeditor5/latest/support/error-codes.html--error-attribute-operation-range-not-flat)`  
The range to change is not flat.
* <a id="ckeditor5/latest/support/error-codes.html--error-attribute-operation-wrong-old-value">  
####  
`[attribute-operation-wrong-old-value](#ckeditor5/latest/support/error-codes.html--error-attribute-operation-wrong-old-value)`  
Changed node has different attribute value than operation's old attribute value.  
##### Parameters  
`root : [ModelItem](../api/module%5Fengine%5Fmodel%5Fitem-ModelItem.html)`  
The item element.  
`key : string`  
The key of the attribute.  
`value : never`  
The value.
* <a id="ckeditor5/latest/support/error-codes.html--error-batch-constructor-deprecated-string-type">  
####  
`[batch-constructor-deprecated-string-type](#ckeditor5/latest/support/error-codes.html--error-batch-constructor-deprecated-string-type)`  
The string value for a `type` property of the `Batch` constructor has been deprecated and will be removed in the near future. Please refer to the [Batch constructor API documentation](../api/module%5Fengine%5Fmodel%5Fbatch-Batch.html#function-constructor) for more information.
* <a id="ckeditor5/latest/support/error-codes.html--error-batch-type-deprecated">  
####  
`[batch-type-deprecated](#ckeditor5/latest/support/error-codes.html--error-batch-type-deprecated)`  
The `Batch#type` property has been deprecated and will be removed in the near future. Use `Batch#isLocal`, `Batch#isUndoable`, `Batch#isUndo` and `Batch#isTyping` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-cannot-change-view-tree">  
####  
`[cannot-change-view-tree](#ckeditor5/latest/support/error-codes.html--error-cannot-change-view-tree)`  
Thrown when there is an attempt to make changes to the view tree when it is in incorrect state. This may cause some unexpected behaviour and inconsistency between the DOM and the view. This may be caused by:

  * calling [change](../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-change) or [forceRender](../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-forceRender)during rendering process,
  * calling [change](../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-change) or [forceRender](../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-forceRender)inside of [post-fixer function](../api/module%5Fengine%5Fview%5Fdocument-ViewDocument.html#function-registerPostFixer).
* <a id="ckeditor5/latest/support/error-codes.html--error-case-change-invalid-license-key">  
####  
`[case-change-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-case-change-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-case-change-trial-license-key-reached-limit-changes">  
####  
`[case-change-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-case-change-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-access-default-workspace-error">  
####  
`[ckbox-access-default-workspace-error](#ckeditor5/latest/support/error-codes.html--error-ckbox-access-default-workspace-error)`  
The user is not authorized to access the workspace defined in the`ckbox.defaultUploadWorkspaceId` configuration.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-fetch-category-http-error">  
####  
`[ckbox-fetch-category-http-error](#ckeditor5/latest/support/error-codes.html--error-ckbox-fetch-category-http-error)`  
Fetching a list of available categories with which an uploaded file can be associated failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-image-not-processed">  
####  
`[ckbox-image-not-processed](#ckeditor5/latest/support/error-codes.html--error-ckbox-image-not-processed)`  
Image has not been processed yet.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-image-processing-failed">  
####  
`[ckbox-image-processing-failed](#ckeditor5/latest/support/error-codes.html--error-ckbox-image-processing-failed)`  
The image processing failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-plugin-image-feature-missing">  
####  
`[ckbox-plugin-image-feature-missing](#ckeditor5/latest/support/error-codes.html--error-ckbox-plugin-image-feature-missing)`  
The CKBox feature requires one of the following plugins to be loaded to work correctly:

  * [ImageBlock](../api/module%5Fimage%5Fimageblock-ImageBlock.html),
  * [ImageInline](../api/module%5Fimage%5Fimageinline-ImageInline.html),
  * [Image](../api/module%5Fimage%5Fimage-Image.html) (loads both `ImageBlock` and `ImageInline`)  
Please make sure your editor configuration is correct.  
##### Parameters  
`editor : [Editor](../api/module%5Fcore%5Feditor%5Feditor-Editor.html)`  
The editor instance.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckbox-plugin-missing-token-url">  
####  
`[ckbox-plugin-missing-token-url](#ckeditor5/latest/support/error-codes.html--error-ckbox-plugin-missing-token-url)`  
The [config.ckbox.tokenUrl](../api/module%5Fckbox%5Fckboxconfig-CKBoxConfig.html#member-tokenUrl) or the [config.cloudServices.tokenUrl](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl)configuration is required for the CKBox plugin.  
```  
ClassicEditor.create( {  
	attachTo: document.createElement( 'div' ),  
	ckbox: {  
		tokenUrl: "YOUR_TOKEN_URL"  
		// ...  
	}  
	// ...  
} );  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-ckeditor-duplicated-modules">  
####  
`[ckeditor-duplicated-modules](#ckeditor5/latest/support/error-codes.html--error-ckeditor-duplicated-modules)`  
This error is thrown when, due to a mistake in the way CKEditor 5 was installed, imported, or initialized, some of its modules were evaluated and executed twice. Duplicate modules inevitably lead to runtime errors and increased bundle size.  
##### Check dependency versions  
First, make sure that you use the latest version of all CKEditor 5 dependencies. Depending on the installation method, you should check the versions of the `ckeditor5`, `ckeditor5-premium-features`, or `@ckeditor/ckeditor5-<NAME>` packages. If you cannot update to the latest version, ensure that all the CKEditor 5 packages are in the same version.  
If you use third-party plugins, make sure to update them, too. If they are incompatible with the version of CKEditor 5 you use, you may need to downgrade the CKEditor 5 packages (which we do not recommend). Ask the plugin's author to upgrade the dependencies, or fork their project and update it yourself.  
##### Check imports  
The next step is to look at how you import CKEditor 5 into your project.

**The [new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html)are designed to prevent module duplication, so if you are not using them yet, you should consider updating your project**. However, several legacy installation methods are still supported for backward compatibility, and mixing them may result in module duplication.  
These are the most common import methods of the CKEditor 5 packages.

  * **New installation methods (NIM)** – Imports from the `ckeditor5` and `ckeditor5-premium-features` packages.
  * **Optimized build** for the new installation methods – Imports from the `@ckeditor/ckeditor5-<NAME>/dist/index.js`.
  * **Predefined builds** (no longer supported) – Imports from the `@ckeditor/ckeditor5-build-<NAME>` packages.
  * **Default imports** (legacy) – Imports from the `@ckeditor/ckeditor5-<NAME>` packages (default export).
  * **`src`** (legacy) – Imports from the `@ckeditor/ckeditor5-<NAME>/src/*`.
  * **DLL builds** (legacy) – Imports from the `ckeditor5/build/<NAME>` and `@ckeditor/ckeditor5-<NAME>/build/*`.  
The best way to avoid duplicate modules is to avoid mixing these installation methods. For example, if you use imports specific to the optimized build, you should use them for all CKEditor 5 packages. In addition, since the DLL builds already include the core of the editor, they cannot be used with other types of imports.  
Here is a matrix showing which installation methods are compatible with each other:

|                  | NIM | Optimized build | Predefined builds | Default imports | src | DLL builds |
| ---------------- | --- | --------------- | ----------------- | --------------- | --- | ---------- |
| NIM              | ✅   | ✅               | ❌                 | ❌               | ❌   | ❌          |
| Optimized builds | ✅   | ✅               | ❌                 | ❌               | ❌   | ❌          |
| Predefined build | ❌   | ❌               | ✅                 | ❌               | ❌   | ❌          |
| Default imports  | ❌   | ❌               | ❌                 | ✅               | ✅   | ❌          |
| src              | ❌   | ❌               | ❌                 | ✅               | ✅   | ❌          |
| DLL builds       | ❌   | ❌               | ❌                 | ❌               | ❌   | ✅          |  
If you use any third-party plugins, make sure the way you import them is compatible with the way you import CKEditor 5.  
New installation methods and optimized builds  
If you use the [new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html), you should only import { code } from the `ckeditor5` and `ckeditor5-premium-features` packages. Do not import { code } from the `@ckeditor/ckeditor5-<NAME>` packages unless you follow the [Optimizing build size](#ckeditor5/latest/getting-started/setup/optimizing-build-size.html) guide and the imports from the `@ckeditor/ckeditor5-<NAME>` packages end with `/dist/index.js`.  
If you use a CDN, ensure that some files are not included twice in your project.  
Examples of valid and invalid import paths:  
```  
import { ClassicEditor, Highlight } from 'ckeditor5'; // ✅  
import { Highlight } from '@ckeditor/ckeditor5-highlight/dist/index.js'; // ✅  
import { Highlight } from '@ckeditor/ckeditor5-highlight/src/highlight.js'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight'; // ❌  
import '@ckeditor/ckeditor5-highlight/build/highlight.js'; // ❌  
```  
(Deprecated) Predefined builds  

**As of April, 2025 predefined build are no longer supported. Please refer to the [Quick Start](#ckeditor5/latest/getting-started/index.html) guide to choose one of the modern installation and integration methods available**.  
If you use the predefined builds, you cannot import any additional plugins. These builds already include the editor's core and selected plugins and importing additional ones will cause some modules to be bundled and loaded twice.  
Examples of valid and invalid import paths:  
```  
import { ClassicEditor } from '@ckeditor/ckeditor5-build-classic'; // ✅  
import { Highlight } from 'ckeditor5'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight/dist/index.js'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight/src/highlight'; // ❌  
import '@ckeditor/ckeditor5-highlight/build/highlight'; // ❌  
```  
If you are missing some features from the list of plugins, you should switch to the [new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html)which do not have this limitation.  
(Legacy) Default imports and \`src\` imports  
If you use the legacy customized installation method, you should only import code from the `@ckeditor/ckeditor5-<NAME>` packages. While you can import code from the `@ckeditor/ckeditor5-<NAME>/src/*` files, it is not recommended as it can make migration to the new installation methods more difficult.  
If you use this installation method, you should not import { code } from the `ckeditor5` or `ckeditor5-premium-features` packages.  
Examples of valid and invalid import paths:  
```  
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic'; // ✅  
import { Highlight } from '@ckeditor/ckeditor5-highlight'; // ✅  
import { Highlight } from '@ckeditor/ckeditor5-highlight/src/highlight.js'; // ✅ (not recommended)  
import { Highlight } from 'ckeditor5'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight/dist/index.js'; // ❌  
import '@ckeditor/ckeditor5-highlight/build/highlight'; // ❌  
```  
(Legacy) DLL builds  
If you are using the [legacy DLL builds](#ckeditor5/latest/updating/nim-migration/dll-builds.html), you should not import any non-DLL modules.  
Examples of valid and invalid import paths:  
```  
import 'ckeditor5/build/ckeditor5-dll.js';// ✅  
import '@ckeditor/ckeditor5-editor-classic/build/editor-classic.js';// ✅  
import '@ckeditor/ckeditor5-highlight/build/highlight.js';// ✅  
import { Highlight } from 'ckeditor5'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight/dist/index.js'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight'; // ❌  
import { Highlight } from '@ckeditor/ckeditor5-highlight/src/highlight.js'; // ❌  
```  
##### Reinstall `node_modules`  
Usually, npm and other package managers deduplicate all packages - for example, `ckeditor5` is only installed once in `node_modules/`. However, it is known to fail to do so occasionally.  
To rule out this possibility, you can try the following:

  1. Remove the `node_modules` directory.
  2. Remove the `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` files (depending on the package manager used).
  3. Run `npm install` to reinstall all packages.
  4. Run `npm ls` to check how many times packages like `@ckeditor/ckeditor5-core` are installed. If they are installed more than once, verify which package causes that.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckfinder-missing-image-plugin">  
####  
`[ckfinder-missing-image-plugin](#ckeditor5/latest/support/error-codes.html--error-ckfinder-missing-image-plugin)`  
CKFinder requires at least one plugin providing support for images loaded in the editor. Please make sure either:

  * [Image](../api/module%5Fimage%5Fimage-Image.html) (which loads both types of images),
  * or [ImageBlock](../api/module%5Fimage%5Fimageblock-ImageBlock.html),
  * or [ImageInline](../api/module%5Fimage%5Fimageinline-ImageInline.html).  
is loaded in your editor configuration.
* <a id="ckeditor5/latest/support/error-codes.html--error-ckfinder-unknown-openermethod">  
####  
`[ckfinder-unknown-openermethod](#ckeditor5/latest/support/error-codes.html--error-ckfinder-unknown-openermethod)`  
The `ckfinder.openerMethod` must be one of: "popup" or "modal".
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservices-init">  
####  
`[cloudservices-init](#ckeditor5/latest/support/error-codes.html--error-cloudservices-init)`  
An internal `WebSocketGateway` error.  
This error might occur because of the incorrectly configured [webSocketUrl](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-webSocketUrl) \* `config.cloudServices.webSocketUrl`} or because of the service handling the WebSocket connections being unavailable.  
The original error is passed in the `error.data.originalError` property.
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservices-reconnection-error">  
####  
`[cloudservices-reconnection-error](#ckeditor5/latest/support/error-codes.html--error-cloudservices-reconnection-error)`  
An internal reconnection error.
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservices-token-not-registered">  
####  
`[cloudservices-token-not-registered](#ckeditor5/latest/support/error-codes.html--error-cloudservices-token-not-registered)`  
The provided `tokenUrl` was not registered by [registerTokenUrl](../api/module%5Fcloud-services%5Fcloudservices-CloudServices.html#function-registerTokenUrl).
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-connect-already-connected">  
####  
`[cloudservicescommentsadapter-connect-already-connected](#ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-connect-already-connected)`  
Cannot connect to the same channelId more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-disconnect-not-exist">  
####  
`[cloudservicescommentsadapter-disconnect-not-exist](#ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-disconnect-not-exist)`  
Missing service with the given `channelId`.
* <a id="ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-service-not-exist">  
####  
`[cloudservicescommentsadapter-service-not-exist](#ckeditor5/latest/support/error-codes.html--error-cloudservicescommentsadapter-service-not-exist)`  
Missing service of a given channelId.
* <a id="ckeditor5/latest/support/error-codes.html--error-collaboration-missing-channelid">  
####  
`[collaboration-missing-channelid](#ckeditor5/latest/support/error-codes.html--error-collaboration-missing-channelid)`  
Unique `collaboration.channelId` configuration is required for defining name for data stores. Note that application instances with the same channelId will share data each other.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-add-invalid-id">  
####  
`[collection-add-invalid-id](#ckeditor5/latest/support/error-codes.html--error-collection-add-invalid-id)`  
This item's ID should be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-add-item-already-exists">  
####  
`[collection-add-item-already-exists](#ckeditor5/latest/support/error-codes.html--error-collection-add-item-already-exists)`  
This item already exists in the collection.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-add-item-invalid-index">  
####  
`[collection-add-item-invalid-index](#ckeditor5/latest/support/error-codes.html--error-collection-add-item-invalid-index)`  
The `index` passed to [Collection#addMany()](../api/module%5Futils%5Fcollection-Collection.html#function-addMany)is invalid. It must be a number between 0 and the collection's length.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-bind-to-rebind">  
####  
`[collection-bind-to-rebind](#ckeditor5/latest/support/error-codes.html--error-collection-bind-to-rebind)`  
The collection cannot be bound more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-get-invalid-arg">  
####  
`[collection-get-invalid-arg](#ckeditor5/latest/support/error-codes.html--error-collection-get-invalid-arg)`  
An index or ID must be given.
* <a id="ckeditor5/latest/support/error-codes.html--error-collection-remove-404">  
####  
`[collection-remove-404](#ckeditor5/latest/support/error-codes.html--error-collection-remove-404)`  
Item not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-commandcollection-command-not-found">  
####  
`[commandcollection-command-not-found](#ckeditor5/latest/support/error-codes.html--error-commandcollection-command-not-found)`  
Command does not exist.  
##### Parameters  
`commandName : string`  
Name of the command.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-active-missing-comment-thread">  
####  
`[commentsrepository-active-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-active-missing-comment-thread)`  
Cannot set a non-existent comment thread as an active. Check if comment thread of the given id is added to the repository.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-active-not-attached">  
####  
`[commentsrepository-active-not-attached](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-active-not-attached)`  
Cannot set a not attached comment thread as an active. Comment thread has to be attached to the target element to set it as active.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-adapter-already-set">  
####  
`[commentsrepository-adapter-already-set](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-adapter-already-set)`  
Cannot set adapter more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-internal-error">  
####  
`[commentsrepository-add-comment-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-internal-error)`  
Adding comment threw an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-thread-internal-error">  
####  
`[commentsrepository-add-comment-thread-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-thread-internal-error)`  
Adding comment thread threw an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-to-missing-comment-thread">  
####  
`[commentsrepository-add-comment-to-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-to-missing-comment-thread)`  
Cannot add comment to a non-existent comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-user-not-exists">  
####  
`[commentsrepository-add-comment-user-not-exists](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-add-comment-user-not-exists)`  
Comment author is not defined in Users plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-attach-missing-comment-thread">  
####  
`[commentsrepository-attach-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-attach-missing-comment-thread)`  
Cannot attach a non-existent comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-duplicated-comment-thread-id">  
####  
`[commentsrepository-duplicated-comment-thread-id](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-duplicated-comment-thread-id)`  
Comment thread with a given id is already added to the repository.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-fetch-comment-thread">  
####  
`[commentsrepository-fetch-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-fetch-comment-thread)`  
Fetching a comment thread failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-get-comment-invalid-id">  
####  
`[commentsrepository-get-comment-invalid-id](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-get-comment-invalid-id)`  
Comment id has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-authorid">  
####  
`[commentsrepository-invalid-comment-authorid](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-authorid)`  
Comment author id has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-content">  
####  
`[commentsrepository-invalid-comment-content](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-content)`  
Comment content has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-thread-id">  
####  
`[commentsrepository-invalid-comment-thread-id](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-comment-thread-id)`  
Comment thread id has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-commentid">  
####  
`[commentsrepository-invalid-commentid](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-invalid-commentid)`  
Comment id has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-comment-thread">  
####  
`[commentsrepository-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-comment-thread)`  
Comment thread with a given id is not existing.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-target">  
####  
`[commentsrepository-missing-target](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-target)`  
Target is required to open new comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-thread-and-adapter-method">  
####  
`[commentsrepository-missing-thread-and-adapter-method](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-missing-thread-and-adapter-method)`  
Comment thread with a given id is not added to the editor nor `adapter.getCommentThread()` is defined. See the [Comments integration](#ckeditor5/latest/features/collaboration/comments/comments-integration.html) guide.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-internal-error">  
####  
`[commentsrepository-remove-comment-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-internal-error)`  
Removing comment resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-missing-comment-thread">  
####  
`[commentsrepository-remove-comment-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-missing-comment-thread)`  
Cannot remove comment from a non-existent comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-thread-internal-error">  
####  
`[commentsrepository-remove-comment-thread-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-comment-thread-internal-error)`  
Removing comment resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-missing-comment">  
####  
`[commentsrepository-remove-missing-comment](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-missing-comment)`  
Cannot remove a non-existent Comment.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-missing-comment-thread">  
####  
`[commentsrepository-remove-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-remove-missing-comment-thread)`  
Cannot remove a non-existent comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-reopen-comment-thread">  
####  
`[commentsrepository-reopen-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-reopen-comment-thread)`  
Comment thread with a given id is not resolved.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-reopen-comment-thread-internal-error">  
####  
`[commentsrepository-reopen-comment-thread-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-reopen-comment-thread-internal-error)`  
Reopening comment thread resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-resolve-comment-thread-internal-error">  
####  
`[commentsrepository-resolve-comment-thread-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-resolve-comment-thread-internal-error)`  
Resolving comment thread resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-resolved-comment-thread">  
####  
`[commentsrepository-resolved-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-resolved-comment-thread)`  
Comment thread with a given id has been already resolved.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-internal-error">  
####  
`[commentsrepository-update-comment-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-internal-error)`  
Updating comment resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-invalid-content">  
####  
`[commentsrepository-update-comment-invalid-content](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-invalid-content)`  
Comment content has to be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-missing-comment-thread">  
####  
`[commentsrepository-update-comment-missing-comment-thread](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-missing-comment-thread)`  
Cannot update a comment of a non-existent comment thread.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-thread-internal-error">  
####  
`[commentsrepository-update-comment-thread-internal-error](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-comment-thread-internal-error)`  
Updating comment thread resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-missing-comment">  
####  
`[commentsrepository-update-missing-comment](#ckeditor5/latest/support/error-codes.html--error-commentsrepository-update-missing-comment)`  
Cannot update a non-existent Comment.
* <a id="ckeditor5/latest/support/error-codes.html--error-componentfactory-item-missing">  
####  
`[componentfactory-item-missing](#ckeditor5/latest/support/error-codes.html--error-componentfactory-item-missing)`  
The required component is not registered in the component factory. Please make sure the provided name is correct and the component has been correctly [added](../api/module%5Fui%5Fcomponentfactory-ComponentFactory.html#function-add) to the factory.  
##### Parameters  
`name : string`  
The name of the missing component.
* <a id="ckeditor5/latest/support/error-codes.html--error-context-addeditor-private-context">  
####  
`[context-addeditor-private-context](#ckeditor5/latest/support/error-codes.html--error-context-addeditor-private-context)`  
Cannot add multiple editors to the context which is created by the editor.
* <a id="ckeditor5/latest/support/error-codes.html--error-context-initplugins-constructor-only">  
####  
`[context-initplugins-constructor-only](#ckeditor5/latest/support/error-codes.html--error-context-initplugins-constructor-only)`  
Only a constructor function is allowed as a [context plugin](../api/module%5Fcore%5Fcontextplugin-ContextPlugin.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-context-initplugins-invalid-plugin">  
####  
`[context-initplugins-invalid-plugin](#ckeditor5/latest/support/error-codes.html--error-context-initplugins-invalid-plugin)`  
Only a plugin marked as a [context plugin](../api/module%5Fcore%5Fcontextplugin-ContextPlugin.html#static-member-isContextPlugin)is allowed to be used with a context.
* <a id="ckeditor5/latest/support/error-codes.html--error-contextualballoon-add-view-exist">  
####  
`[contextualballoon-add-view-exist](#ckeditor5/latest/support/error-codes.html--error-contextualballoon-add-view-exist)`  
Trying to add configuration of the same view more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-contextualballoon-remove-view-not-exist">  
####  
`[contextualballoon-remove-view-not-exist](#ckeditor5/latest/support/error-codes.html--error-contextualballoon-remove-view-not-exist)`  
Trying to remove the configuration of the view not defined in the stack.
* <a id="ckeditor5/latest/support/error-codes.html--error-contextualballoon-showstack-stack-not-exist">  
####  
`[contextualballoon-showstack-stack-not-exist](#ckeditor5/latest/support/error-codes.html--error-contextualballoon-showstack-stack-not-exist)`  
Trying to show a stack that does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-add-alias-dispatcher-not-registered">  
####  
`[conversion-add-alias-dispatcher-not-registered](#ckeditor5/latest/support/error-codes.html--error-conversion-add-alias-dispatcher-not-registered)`  
Trying to register an alias for a dispatcher that nas not been registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-attribute-to-attribute-on-text">  
####  
`[conversion-attribute-to-attribute-on-text](#ckeditor5/latest/support/error-codes.html--error-conversion-attribute-to-attribute-on-text)`  
This error occurs when a [text node's](../api/module%5Fengine%5Fmodel%5Ftextproxy-ModelTextProxy.html) attribute is to be downcasted by an [Attribute to Attribute converter](../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-attributeToAttribute). In most cases it is caused by converters misconfiguration when only "generic" converter is defined:  
```  
editor.conversion.for( 'downcast' ).attributeToAttribute( {  
	model: 'attribute-name',  
	view: 'attribute-name'  
} ) );  
```  
and given attribute is used on text node, for example:  
```  
model.change( writer => {  
	writer.insertText( 'Foo', { 'attribute-name': 'bar' }, parent, 0 );  
} );  
```  
In such cases, to convert the same attribute for both [ModelElement](../api/module%5Fengine%5Fmodel%5Felement-ModelElement.html)and [Text](../api/module%5Fengine%5Fmodel%5Ftextproxy-ModelTextProxy.html) nodes, text specific [Attribute to Element converter](../api/module%5Fengine%5Fconversion%5Fconversion-Conversion.html#function-attributeToElement)with higher [priority](../api/module%5Futils%5Fpriorities-PriorityString.html) must also be defined:  
```  
editor.conversion.for( 'downcast' ).attributeToElement( {  
	model: {  
		key: 'attribute-name',  
		name: '$text'  
	},  
	view: ( value, { writer } ) => {  
		return writer.createAttributeElement( 'span', { 'attribute-name': value } );  
	},  
	converterPriority: 'high'  
} ) );  
```  
##### Parameters  
`data : object`  
The conversion data.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-element-to-structure-disallowed-text">  
####  
`[conversion-element-to-structure-disallowed-text](#ckeditor5/latest/support/error-codes.html--error-conversion-element-to-structure-disallowed-text)`  
This error occurs when a [model element](../api/module%5Fengine%5Fmodel%5Felement-ModelElement.html) is downcasted via [elementToStructure](../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-elementToStructure) helper but the element was allowed to host `$text` by the [model schema](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html).  
For instance, this may be the result of `myElement` allowing the content of [$block](#ckeditor5/latest/framework/deep-dive/schema.html--generic-items) in its schema definition:  
```  
// Element definition in schema.  
schema.register( 'myElement', {  
	allowContentOf: '$block',  
	// ...  
} );  
// ...  
// Conversion of myElement with the use of elementToStructure().  
editor.conversion.for( 'downcast' ).elementToStructure( {  
	model: 'myElement',  
	view: ( modelElement, { writer } ) => {  
		// ...  
	}  
} );  
```  
In such case, [elementToElement()](../api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-elementToElement) helper can be used instead to get around this problem:  
```  
editor.conversion.for( 'downcast' ).elementToElement( {  
	model: 'myElement',  
	view: ( modelElement, { writer } ) => {  
		// ...  
	}  
} );  
```  
##### Parameters  
`elementName : string`  
The name of the element the structure is to be created for.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-for-unknown-group">  
####  
`[conversion-for-unknown-group](#ckeditor5/latest/support/error-codes.html--error-conversion-for-unknown-group)`  
Trying to add a converter to an unknown dispatchers group.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-group-exists">  
####  
`[conversion-group-exists](#ckeditor5/latest/support/error-codes.html--error-conversion-group-exists)`  
Trying to register a group name that has already been registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-model-consumable-not-consumed">  
####  
`[conversion-model-consumable-not-consumed](#ckeditor5/latest/support/error-codes.html--error-conversion-model-consumable-not-consumed)`  
Some of the [model items](../api/module%5Fengine%5Fmodel%5Fitem-ModelItem.html) were not consumed while downcasting the model to view.  
This might be the effect of:

  * A missing converter for some model elements. Make sure that you registered downcast converters for all model elements.
  * A custom converter that does not consume converted items. Make sure that you [consumed](../api/module%5Fengine%5Fconversion%5Fmodelconsumable-ModelConsumable.html#function-consume) all model elements that you converted from the model to the view.
  * A custom converter that called `event.stop()`. When providing a custom converter, keep in mind that you should not stop the event. If you stop it then the default converter at the `lowest` priority will not trigger the conversion of this node's attributes and child nodes.  
##### Parameters  
`items : Array<[ModelItem](../api/module%5Fengine%5Fmodel%5Fitem-ModelItem.html)>`  
Items that were not consumed.
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-slot-filter-incomplete">  
####  
`[conversion-slot-filter-incomplete](#ckeditor5/latest/support/error-codes.html--error-conversion-slot-filter-incomplete)`  
Filters provided to `writer.createSlot()` are incomplete and exclude at least one children element (one of the children elements would not be assigned to any of the slots).  
##### Parameters  
`element : [ModelElement](../api/module%5Fengine%5Fmodel%5Felement-ModelElement.html)`  
The element of which children would not be properly
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-slot-filter-overlap">  
####  
`[conversion-slot-filter-overlap](#ckeditor5/latest/support/error-codes.html--error-conversion-slot-filter-overlap)`  
Filters provided to `writer.createSlot()` overlap (at least two filters accept the same child element).  
##### Parameters  
`element : [ModelElement](../api/module%5Fengine%5Fmodel%5Felement-ModelElement.html)`  
The element of which children would not be properly
* <a id="ckeditor5/latest/support/error-codes.html--error-conversion-slot-mode-unknown">  
####  
`[conversion-slot-mode-unknown](#ckeditor5/latest/support/error-codes.html--error-conversion-slot-mode-unknown)`  
Unknown slot mode was provided to `writer.createSlot()` in the downcast converter.  
##### Parameters  
`modeOrFilter : never`  
The specified mode or filter.
* <a id="ckeditor5/latest/support/error-codes.html--error-css-full-page-provide-sanitize-function">  
####  
`[css-full-page-provide-sanitize-function](#ckeditor5/latest/support/error-codes.html--error-css-full-page-provide-sanitize-function)`  
When using the Full page with the `config.htmlSupport.fullPage.allowRenderStylesFromHead` set to `true`, it is strongly recommended to define a sanitize function that will clean up the CSS which is present in the `<head>` in editors content in order to avoid XSS vulnerability.  
For a detailed overview, check the [Full page HTML feature](#ckeditor5/latest/features/html/full-page-html.html) documentation.
* <a id="ckeditor5/latest/support/error-codes.html--error-data-filter-invalid-definition">  
####  
`[data-filter-invalid-definition](#ckeditor5/latest/support/error-codes.html--error-data-filter-invalid-definition)`  
The definition cannot be handled by the data filter.  
Make sure that the registered definition is correct.
* <a id="ckeditor5/latest/support/error-codes.html--error-datacontroller-get-detached-root">  
####  
`[datacontroller-get-detached-root](#ckeditor5/latest/support/error-codes.html--error-datacontroller-get-detached-root)`  
Retrieving document data for a detached root.  
This usually indicates an error as a detached root should be considered "removed" and should not be included in the document data.
* <a id="ckeditor5/latest/support/error-codes.html--error-datacontroller-get-non-existent-root">  
####  
`[datacontroller-get-non-existent-root](#ckeditor5/latest/support/error-codes.html--error-datacontroller-get-non-existent-root)`  
Cannot get data from a non-existing root. This error is thrown when [DataController#get() method](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-get)is called with a non-existent root name. For example, if there is an editor instance with only `main` root, calling [get](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-get) like:  
```  
data.get( { rootName: 'root2' } );  
```  
will throw this error.
* <a id="ckeditor5/latest/support/error-codes.html--error-datacontroller-init-document-not-empty">  
####  
`[datacontroller-init-document-not-empty](#ckeditor5/latest/support/error-codes.html--error-datacontroller-init-document-not-empty)`  
Cannot set initial data to a non-empty [ModelDocument](../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html). Initial data should be set once, during the [Editor](../api/module%5Fcore%5Feditor%5Feditor-Editor.html) initialization, when the [version](../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html#member-version) is equal 0.
* <a id="ckeditor5/latest/support/error-codes.html--error-datacontroller-init-non-existent-root">  
####  
`[datacontroller-init-non-existent-root](#ckeditor5/latest/support/error-codes.html--error-datacontroller-init-non-existent-root)`  
Cannot init data on a non-existent root. This error is thrown when [DataController#init() method](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-init)is called with non-existent root name. For example, if there is an editor instance with only `main` root, calling [init](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-init) like:  
```  
data.init( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );  
```  
will throw this error.
* <a id="ckeditor5/latest/support/error-codes.html--error-datacontroller-set-non-existent-root">  
####  
`[datacontroller-set-non-existent-root](#ckeditor5/latest/support/error-codes.html--error-datacontroller-set-non-existent-root)`  
Cannot set data on a non-existent root. This error is thrown when the [DataController#set() method](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-set)is called with non-existent root name. For example, if there is an editor instance with only the default `main` root, calling [set](../api/module%5Fengine%5Fcontroller%5Fdatacontroller-DataController.html#function-set) like:  
```  
data.set( { main: '<p>Foo</p>', root2: '<p>Bar</p>' } );  
```  
will throw this error.
* <a id="ckeditor5/latest/support/error-codes.html--error-decompress-compressor-not-found">  
####  
`[decompress-compressor-not-found](#ckeditor5/latest/support/error-codes.html--error-decompress-compressor-not-found)`  
The compressor could not decompress the data as the compressor for one of entries in the `types` array has not been found.
* <a id="ckeditor5/latest/support/error-codes.html--error-detach-operation-on-document-node">  
####  
`[detach-operation-on-document-node](#ckeditor5/latest/support/error-codes.html--error-detach-operation-on-document-node)`  
Cannot detach document node.
* <a id="ckeditor5/latest/support/error-codes.html--error-document-outline-container-not-provided">  
####  
`[document-outline-container-not-provided](#ckeditor5/latest/support/error-codes.html--error-document-outline-container-not-provided)`  
A DOM element to inject the document outline is not provided. Please set the [config.documentOutline.container](../api/module%5Fdocument-outline%5Fdocumentoutline-DocumentOutlineConfig.html#member-container)configuration option.  
##### Parameters  
`editor : [Editor](../api/module%5Fcore%5Feditor%5Feditor-Editor.html)`  
Editor instance related to error.
* <a id="ckeditor5/latest/support/error-codes.html--error-document-outline-invalid-license-key">  
####  
`[document-outline-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-document-outline-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-document-outline-trial-license-key-reached-limit-changes">  
####  
`[document-outline-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-document-outline-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-document-selection-gravity-wrong-restore">  
####  
`[document-selection-gravity-wrong-restore](#ckeditor5/latest/support/error-codes.html--error-document-selection-gravity-wrong-restore)`  
Restoring gravity for an unknown UID is not possible. Make sure you are using a correct UID obtained from the [overrideSelectionGravity](../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html#function-overrideSelectionGravity) to restore.  
##### Parameters  
`uid : string`  
The unique identifier returned by
* <a id="ckeditor5/latest/support/error-codes.html--error-document-selection-wrong-position">  
####  
`[document-selection-wrong-position](#ckeditor5/latest/support/error-codes.html--error-document-selection-wrong-position)`  
Range from [document selection](../api/module%5Fengine%5Fmodel%5Fdocumentselection-ModelDocumentSelection.html)starts or ends at incorrect position.  
##### Parameters  
`range : [ModelRange](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html)`  
The invalid range.
* <a id="ckeditor5/latest/support/error-codes.html--error-domconverter-invalid-attribute-detected">  
####  
`[domconverter-invalid-attribute-detected](#ckeditor5/latest/support/error-codes.html--error-domconverter-invalid-attribute-detected)`  
Invalid attribute name was ignored during rendering.
* <a id="ckeditor5/latest/support/error-codes.html--error-domconverter-transparent-rendering-unsupported-in-editing-pipeline">  
####  
`[domconverter-transparent-rendering-unsupported-in-editing-pipeline](#ckeditor5/latest/support/error-codes.html--error-domconverter-transparent-rendering-unsupported-in-editing-pipeline)`  
The `dataPipeline:transparentRendering` flag is supported only in the data pipeline.
* <a id="ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-attribute-detected">  
####  
`[domconverter-unsafe-attribute-detected](#ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-attribute-detected)`  
The [ViewDomConverter](../api/module%5Fengine%5Fview%5Fdomconverter-ViewDomConverter.html) detected an interactive attribute in the [editing pipeline](#ckeditor5/latest/framework/architecture/editing-engine.html--editing-pipeline). For the best editing experience, the attribute was renamed to `data-ck-unsafe-attribute-[original attribute name]`.  
If you are the author of the plugin that generated this attribute and you want it to be preserved in the editing pipeline, you can configure this when creating the element using [ViewDowncastWriter](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html) during the [model–view conversion](#ckeditor5/latest/framework/architecture/editing-engine.html--conversion). Methods such as [createContainerElement](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-createContainerElement:WITHOUT%5FCHILDREN), [createAttributeElement](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-createAttributeElement), or [createEmptyElement](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-createEmptyElement)accept an option that will disable filtering of specific attributes:  
```  
const paragraph = writer.createContainerElement( 'p',  
	{  
		class: 'clickable-paragraph',  
		onclick: 'alert( "Paragraph clicked!" )'  
	},  
	{  
		// Make sure the "onclick" attribute will pass through.  
		renderUnsafeAttributes: [ 'onclick' ]  
	}  
);  
```  
##### Parameters  
`domElement : HTMLElement`  
The DOM element the attribute was set on.  
`key : string`  
The original name of the attribute  
`value : string`  
The value of the original attribute
* <a id="ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-script-element-detected">  
####  
`[domconverter-unsafe-script-element-detected](#ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-script-element-detected)`  
While rendering the editor content, the [ViewDomConverter](../api/module%5Fengine%5Fview%5Fdomconverter-ViewDomConverter.html) detected a `<script>` element that may disrupt the editing experience. To avoid this, the `<script>` element was replaced with `<span data-ck-unsafe-element="script"></span>`.
* <a id="ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-style-element-detected">  
####  
`[domconverter-unsafe-style-element-detected](#ckeditor5/latest/support/error-codes.html--error-domconverter-unsafe-style-element-detected)`  
While rendering the editor content, the [ViewDomConverter](../api/module%5Fengine%5Fview%5Fdomconverter-ViewDomConverter.html) detected a `<style>` element that may affect the editing experience. To avoid this, the `<style>` element was replaced with `<span data-ck-unsafe-element="style"></span>`.
* <a id="ckeditor5/latest/support/error-codes.html--error-easy-image-image-feature-missing">  
####  
`[easy-image-image-feature-missing](#ckeditor5/latest/support/error-codes.html--error-easy-image-image-feature-missing)`  
The Easy Image feature requires one of the following plugins to be loaded to work correctly:

  * [ImageBlock](../api/module%5Fimage%5Fimageblock-ImageBlock.html),
  * [ImageInline](../api/module%5Fimage%5Fimageinline-ImageInline.html),
  * [Image](../api/module%5Fimage%5Fimage-Image.html) (loads both `ImageBlock` and `ImageInline`)  
Please make sure your editor configuration is correct.  
##### Parameters  
`editor : [Editor](../api/module%5Fcore%5Feditor%5Feditor-Editor.html)`  
The editor instance.
* <a id="ckeditor5/latest/support/error-codes.html--error-editingcontroller-reconvertmarker-marker-not-exist">  
####  
`[editingcontroller-reconvertmarker-marker-not-exist](#ckeditor5/latest/support/error-codes.html--error-editingcontroller-reconvertmarker-marker-not-exist)`  
The marker with the provided name does not exist and cannot be reconverted.  
##### Parameters  
`markerName : string`  
The name of the reconverted marker.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-config-invalid-type">  
####  
`[editor-config-invalid-type](#ckeditor5/latest/support/error-codes.html--error-editor-config-invalid-type)`  
Editor configuration must be an object.  
A common cause of this error is passing an Editor class (for example `ClassicEditor`) in the `config.plugins` array. In such case, the editor constructor is called with an Editor or Context instance instead of the configuration object.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-config-sanitizehtml-not-supported">  
####  
`[editor-config-sanitizehtml-not-supported](#ckeditor5/latest/support/error-codes.html--error-editor-config-sanitizehtml-not-supported)`  
Configuration property `config.sanitizeHtml` was removed in CKEditor version 43.1.0 and is no longer supported.  
Please use `config.htmlEmbed.sanitizeHtml` and/or `config.mergeFields.sanitizeHtml` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-attachto-ignored">  
####  
`[editor-create-attachto-ignored](#ckeditor5/latest/support/error-codes.html--error-editor-create-attachto-ignored)`  
The [config.attachTo](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-attachTo) option is only available for the [ClassicEditor](../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html) because it replaces the given DOM element with its own UI. Other editor types (e.g. inline, balloon, decoupled) render inside the root element directly, so `config.attachTo` is not applicable.  
Remove the `attachTo` option from the editor configuration and use [config.root.element](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-element)(or `config.roots.<rootName>.element` for the multi-root editor) to specify the DOM element instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-attachto-overspecified">  
####  
`[editor-create-attachto-overspecified](#ckeditor5/latest/support/error-codes.html--error-editor-create-attachto-overspecified)`  
The element to attach the editor to is specified both as the first argument of [ClassicEditor.create()](../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html#static-function-create)and in [config.attachTo](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-attachTo).  
Passing the element as the first argument is deprecated. Remove it and use [config.attachTo](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-attachTo) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-initial-data">  
####  
`[editor-create-initial-data](#ckeditor5/latest/support/error-codes.html--error-editor-create-initial-data)`  
The `config.initialData` option cannot be used together with the initial data passed as the first parameter of [Editor.create()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create).
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-initial-data-overspecified">  
####  
`[editor-create-initial-data-overspecified](#ckeditor5/latest/support/error-codes.html--error-editor-create-initial-data-overspecified)`  
The initial data is specified both as the first argument of the editor `create()` method (e.g. [InlineEditor.create()](../api/module%5Feditor-inline%5Finlineeditor-InlineEditor.html#static-function-create) or [MultiRootEditor.create()](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html#static-function-create)) and in the deprecated [config.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData).  
Passing initial data as the first argument is deprecated. Remove it and use [config.root.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData)(or `config.roots.<rootName>.initialData` for the multi-root editor) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-legacy-initial-data-overspecified">  
####  
`[editor-create-legacy-initial-data-overspecified](#ckeditor5/latest/support/error-codes.html--error-editor-create-legacy-initial-data-overspecified)`  
The initial data is specified both in [config.root.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData)(or `config.roots.<rootName>.initialData` for the multi-root editor) and in the deprecated [config.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData).  
The `config.initialData` option is deprecated. Remove it and use [config.root.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData)(or `config.roots.<rootName>.initialData` for the multi-root editor) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-multi-root-with-main">  
####  
`[editor-create-multi-root-with-main](#ckeditor5/latest/support/error-codes.html--error-editor-create-multi-root-with-main)`  
The [config.root](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-root) option is designed for single-root editors and cannot be used with the [multi-root editor](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html).  
To configure a multi-root editor, define each root individually using [config.roots](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-roots):  
```  
MultiRootEditor.create( {  
	roots: {  
		header: { initialData: '<p>Header</p>' },  
		content: { initialData: '<p>Content</p>' }  
	}  
} );  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-root-element-not-supported">  
####  
`[editor-create-root-element-not-supported](#ckeditor5/latest/support/error-codes.html--error-editor-create-root-element-not-supported)`  
The [ClassicEditor](../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html) ignores [config.root.element](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-element) because the classic editor replaces the DOM element with its own UI rather than editing inline within it. Use [config.attachTo](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-attachTo)to specify the DOM element the editor should replace.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-root-element-overspecified">  
####  
`[editor-create-root-element-overspecified](#ckeditor5/latest/support/error-codes.html--error-editor-create-root-element-overspecified)`  
The root element is specified both as the first argument of the editor `create()` method (e.g. [InlineEditor.create()](../api/module%5Feditor-inline%5Finlineeditor-InlineEditor.html#static-function-create) or [MultiRootEditor.create()](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html#static-function-create)) and in [config.root.element](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-element)(or `config.roots.<rootName>.element` for the [multi-root editor](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html)).  
Passing the element as the first argument is deprecated. Remove it and use [config.root.element](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-element)(or `config.roots.<rootName>.element` for the multi-root editor) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-root-initial-data-overspecified">  
####  
`[editor-create-root-initial-data-overspecified](#ckeditor5/latest/support/error-codes.html--error-editor-create-root-initial-data-overspecified)`  
The initial data is specified both as the first argument of the editor `create()` method (e.g. [InlineEditor.create()](../api/module%5Feditor-inline%5Finlineeditor-InlineEditor.html#static-function-create) or [MultiRootEditor.create()](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html#static-function-create)) and in [config.root.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData)(or `config.roots.<rootName>.initialData` for the multi-root editor).  
Passing initial data as the first argument is deprecated. Remove it and use [config.root.initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-RootConfig.html#member-initialData)(or `config.roots.<rootName>.initialData` for the multi-root editor) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-create-roots-with-main">  
####  
`[editor-create-roots-with-main](#ckeditor5/latest/support/error-codes.html--error-editor-create-roots-with-main)`  
Both [config.root](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-root) and `config.roots.main` are set, but they both configure the same default editing root, which creates an ambiguity. Use one or the other:

  * [config.root](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-root) for a single-root editor.
  * [config.roots](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-roots) when defining multiple roots.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-initial-data-replaced-with-revision-data">  
####  
`[editor-initial-data-replaced-with-revision-data](#ckeditor5/latest/support/error-codes.html--error-editor-initial-data-replaced-with-revision-data)`  
The editor initial data and initial roots attributes were replaced with the most recent revision data, as the editor data was different from revision data.  
This means that the editor data was either outdated (possible due to an error, e.g. the document data has not been saved after last changes during the previous editing session) or the data was post-processed after it was obtained from the editor.  
Note, that changes in whitespaces are also considered a difference.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-isreadonly-has-no-setter">  
####  
`[editor-isreadonly-has-no-setter](#ckeditor5/latest/support/error-codes.html--error-editor-isreadonly-has-no-setter)`  
The [Editor#isReadOnly](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) property is read-only since version `34.0.0`and can be set only using [Editor#enableReadOnlyMode( lockId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-enableReadOnlyMode) and [Editor#disableReadOnlyMode( lockId )](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-disableReadOnlyMode).  
Usage before version `34.0.0`:  
```  
editor.isReadOnly = true;  
editor.isReadOnly = false;  
```  
Usage since version `34.0.0`:  
```  
editor.enableReadOnlyMode( 'my-feature-id' );  
editor.disableReadOnlyMode( 'my-feature-id' );  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-missing-sourceelement">  
####  
`[editor-missing-sourceelement](#ckeditor5/latest/support/error-codes.html--error-editor-missing-sourceelement)`  
Cannot update the source element of a detached editor.  
The [updateSourceElement()](../api/module%5Fcore%5Feditor%5Futils%5Felementapimixin-ElementApi.html#function-updateSourceElement)method cannot be called if you did not pass an element to `Editor.create()`.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-read-only-lock-id-invalid">  
####  
`[editor-read-only-lock-id-invalid](#ckeditor5/latest/support/error-codes.html--error-editor-read-only-lock-id-invalid)`  
The lock ID is missing or it is not a string or symbol.  
##### Parameters  
`lockId : never`  
Lock ID.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-source-element-already-used">  
####  
`[editor-source-element-already-used](#ckeditor5/latest/support/error-codes.html--error-editor-source-element-already-used)`  
A DOM element used to create the editor (e.g. [InlineEditor.create()](../api/module%5Feditor-inline%5Finlineeditor-InlineEditor.html#static-function-create)) has already been used to create another editor instance. Make sure each editor is created with a unique DOM element.  
##### Parameters  
`element : HTMLElement`  
DOM element that caused the collision.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-ui-deprecated-editable-elements">  
####  
`[editor-ui-deprecated-editable-elements](#ckeditor5/latest/support/error-codes.html--error-editor-ui-deprecated-editable-elements)`  
The `EditorUI#_editableElements` property has been deprecated and will be removed in the near future. Please use [setEditableElement()](../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#function-setEditableElement) and [getEditableElement()](../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html#function-getEditableElement) methods instead.  
##### Parameters  
`editorUI : [EditorUI](../api/module%5Fui%5Feditorui%5Feditorui-EditorUI.html)`  
Editor UI instance the deprecated property belongs to.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-ui-deprecated-viewport-offset-config">  
####  
`[editor-ui-deprecated-viewport-offset-config](#ckeditor5/latest/support/error-codes.html--error-editor-ui-deprecated-viewport-offset-config)`  
The [EditorConfig#toolbar.viewportTopOffset](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar)property has been deprecated and will be removed in the near future. Please use [EditorConfig#ui.viewportOffset](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-ui) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-usage-data-path-already-set">  
####  
`[editor-usage-data-path-already-set](#ckeditor5/latest/support/error-codes.html--error-editor-usage-data-path-already-set)`  
The error thrown when trying to set the usage data path that was already set. Make sure that you are not setting the same path multiple times.  
##### Parameters  
`path : string`  
The path that was already set.
* <a id="ckeditor5/latest/support/error-codes.html--error-editor-wrong-element">  
####  
`[editor-wrong-element](#ckeditor5/latest/support/error-codes.html--error-editor-wrong-element)`  
This error is thrown when trying to pass a `<textarea>` element to a `create()` function of an editor class.  
The only editor type which can be initialized on `<textarea>` elements is the [classic editor](#ckeditor5/latest/getting-started/setup/editor-types.html--classic-editor). This editor hides the passed element and inserts its own UI next to it. Other types of editors reuse the passed element as their root editable element and therefore `<textarea>` is not appropriate for them. Use a `<div>` or another text container instead:  
```  
<div id="editor">  
	<p>Initial content.</p>  
</div>  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-editorannotations-invalid-source-callback">  
####  
`[editorannotations-invalid-source-callback](#ckeditor5/latest/support/error-codes.html--error-editorannotations-invalid-source-callback)`  
Function required.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-export-inline-styles-plugin">  
####  
`[email-configuration-missing-export-inline-styles-plugin](#ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-export-inline-styles-plugin)`  
Warning shown when the [ExportInlineStyles](#ckeditor5/latest/features/export-with-inline-styles.html) plugin is missing. While it is not required for the email integration to work, it is recommended to enable it to ensure that exported content has inlined styles. This is important as email clients do not work with external stylesheets, and most styling may be lost.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-plain-table-output-plugin">  
####  
`[email-configuration-missing-plain-table-output-plugin](#ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-plain-table-output-plugin)`  
The [PlainTableOutput](../api/module%5Ftable%5Fplaintableoutput-PlainTableOutput.html) plugin is required to use tables in the email integration. Without it, tables will not be rendered correctly and may not be displayed correctly in some email clients as the `<figure>` elements is not supported by most email clients.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-source-editing-plugin">  
####  
`[email-configuration-missing-source-editing-plugin](#ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-source-editing-plugin)`  
The [SourceEditing](#ckeditor5/latest/features/source-editing/source-editing.html) or [SourceEditingEnhanced](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html) plugin is missing in the email integration. While it is not required for the email integration to work, it is recommended to enable it to ensure that the source code view is available for users. This is important for email developers who need to work with the source code directly.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-table-layout-plugin">  
####  
`[email-configuration-missing-table-layout-plugin](#ckeditor5/latest/support/error-codes.html--error-email-configuration-missing-table-layout-plugin)`  
The [TableLayout](#ckeditor5/latest/features/tables/layout-tables.html) plugin is required to use tables in the email integration. Tables in the editor may look and act than in email clients. This is why we have two separate plugins to handle different implementations of this feature.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-color-format">  
####  
`[email-configuration-unsupported-color-format](#ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-color-format)`  
The color format specified in the editor configuration (such as for color pickers or other UI components) is not supported in email clients. Please [use rgb or hex format](#ckeditor5/latest/features/font.html--color-picker) instead.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-color-value">  
####  
`[email-configuration-unsupported-color-value](#ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-color-value)`  
The specified color value uses a format not supported in email clients. This affects various color settings like fonts, backgrounds, borders, etc. Please [use rgb() or #RRGGBB format](#ckeditor5/latest/features/font.html--color-picker) instead.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-list-item-marker-formatting">  
####  
`[email-configuration-unsupported-list-item-marker-formatting](#ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-list-item-marker-formatting)`  
It is recommended to avoid using list item marker formatting as it will not work in email clients. It is possible to [disable this feature](#ckeditor5/latest/features/lists/lists-properties.html--disabling-marker-formatting)with the `enableListItemMarkerFormatting: false` switch in the list settings.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html)While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-plugin">  
####  
`[email-configuration-unsupported-plugin](#ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-plugin)`  
The plugin is not supported in email editing mode as it may not work correctly in email clients. The HTML output the plugin creates may not be recognized by email clients, rendering the elements incorrectly or not at all. It is encouraged to remove the plugin from the editor configuration to maintain compatibility.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-reversed-list">  
####  
`[email-configuration-unsupported-reversed-list](#ckeditor5/latest/support/error-codes.html--error-email-configuration-unsupported-reversed-list)`  
It is recommended to avoid using reversed lists as they may not work correctly in some email clients. It is possible to [disable this feature with the reversed: true](#ckeditor5/latest/features/lists/lists.html--list-properties) switch in the list properties settings.  
This warning is emitted by the [email configuration helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html). While it is possible to [disable these warnings](#ckeditor5/latest/features/email-editing/email-configuration-helper.html--logs-and-warnings)using the `email.warnings.suppress` option, it is strongly discouraged.
* <a id="ckeditor5/latest/support/error-codes.html--error-emoji-config-marker-already-used">  
####  
`[emoji-config-marker-already-used](#ckeditor5/latest/support/error-codes.html--error-emoji-config-marker-already-used)`  
The `marker` in the `emoji` config is already used by other plugin configuration.  
##### Parameters  
`marker : string`  
Used marker.
* <a id="ckeditor5/latest/support/error-codes.html--error-emoji-repository-cdn-use">  
####  
`[emoji-repository-cdn-use](#ckeditor5/latest/support/error-codes.html--error-emoji-repository-cdn-use)`  
It was detected that your installation uses a commercial license key, and the default [CKEditor CDN for Emoji plugin data](#ckeditor5/latest/features/emoji.html--emoji-source).  
To avoid this, you can use the [emoji.definitionsUrl](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-definitionsUrl)configuration option to provide a URL to your own emoji repository.  
If you want to suppress this warning, while using the default CDN, set this configuration option to `cdn`.
* <a id="ckeditor5/latest/support/error-codes.html--error-emoji-repository-empty">  
####  
`[emoji-repository-empty](#ckeditor5/latest/support/error-codes.html--error-emoji-repository-empty)`  
Unable to identify the available emoji to display.  
See the [troubleshooting](#ckeditor5/latest/features/emoji.html--troubleshooting) section in the [Emoji feature](#ckeditor5/latest/features/emoji.html) guide for more details.
* <a id="ckeditor5/latest/support/error-codes.html--error-emoji-repository-load-failed">  
####  
`[emoji-repository-load-failed](#ckeditor5/latest/support/error-codes.html--error-emoji-repository-load-failed)`  
Unable to load the emoji repository from the URL.  
If the URL works properly and there is no disruption of communication, please check your [Content Security Policy (CSP)](#ckeditor5/latest/getting-started/setup/csp.html) setting and make sure the URL connection is allowed by the editor.
* <a id="ckeditor5/latest/support/error-codes.html--error-emoji-repository-redundant-version">  
####  
`[emoji-repository-redundant-version](#ckeditor5/latest/support/error-codes.html--error-emoji-repository-redundant-version)`  
Both [emoji.definitionsUrl](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-definitionsUrl) and [emoji.version](../api/module%5Femoji%5Femojiconfig-EmojiConfig.html#member-version) configuration options are set. Only the `emoji.definitionsUrl` option will be used.  
The `emoji.version` option will be ignored and should be removed from the configuration.
* <a id="ckeditor5/latest/support/error-codes.html--error-enableViewPlaceholder-deprecated-text-option">  
####  
`[enableViewPlaceholder-deprecated-text-option](#ckeditor5/latest/support/error-codes.html--error-enableViewPlaceholder-deprecated-text-option)`  
The "text" option in the [enableViewPlaceholder()](../api/module%5Fengine%5Fview%5Fplaceholder.html#function-enableViewPlaceholder)function is deprecated and will be removed soon.  
See the `#view-element-placeholder` section in the `Update to v39.x` section in the [updating from older versions](#ckeditor5/latest/updating/guides/updating-from-older-versions.html) guide for more information on how to apply this change.
* <a id="ckeditor5/latest/support/error-codes.html--error-error-saving-suggestion-data-suggestion-discarded">  
####  
`[error-saving-suggestion-data-suggestion-discarded](#ckeditor5/latest/support/error-codes.html--error-error-saving-suggestion-data-suggestion-discarded)`  
An unexpected error happened when the suggestion data was being saved in the database. In order to avoid mismatch between document data and the suggestions database, the suggestion in the document has been automatically discarded.
* <a id="ckeditor5/latest/support/error-codes.html--error-export-word-v1-api-is-deprecated">  
####  
`[export-word-v1-api-is-deprecated](#ckeditor5/latest/support/error-codes.html--error-export-word-v1-api-is-deprecated)`  
You are using v1 API interface in the `exportWord.converterOptions`. Please update your config with a new version of Export Word API. See migration guide: https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Migrating-from-v1
* <a id="ckeditor5/latest/support/error-codes.html--error-filerepository-no-upload-adapter">  
####  
`[filerepository-no-upload-adapter](#ckeditor5/latest/support/error-codes.html--error-filerepository-no-upload-adapter)`  
You need to enable an upload adapter in order to be able to upload files.  
This warning shows up when [FileRepository](../api/module%5Fupload%5Ffilerepository-FileRepository.html) is being used without [defining an upload adapter](../api/module%5Fupload%5Ffilerepository-FileRepository.html#member-createUploadAdapter).

**If you see this warning when using one of the now deprecated CKEditor 5 builds**it means that you did not configure any of the upload adapters available by default in those builds.  
Predefined builds are a deprecated solution and we strongly advise [migrating to new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html).  
See the [comprehensive "Image upload overview"](#ckeditor5/latest/features/images/image-upload/image-upload.html) to learn which upload adapters are available in the builds and how to configure them.  
Otherwise, if you see this warning, there is a chance that you enabled a feature like [ImageUpload](../api/module%5Fimage%5Fimageupload-ImageUpload.html), or [ImageUploadUI](../api/module%5Fimage%5Fimageupload%5Fimageuploadui-ImageUploadUI.html) but you did not enable any upload adapter. You can choose one of the existing upload adapters listed in the ["Image upload overview"](#ckeditor5/latest/features/images/image-upload/image-upload.html).  
You can also implement your [own image upload adapter](#ckeditor5/latest/framework/deep-dive/upload-adapter.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-filerepository-read-wrong-status">  
####  
`[filerepository-read-wrong-status](#ckeditor5/latest/support/error-codes.html--error-filerepository-read-wrong-status)`  
You cannot call read if the status is different than idle.
* <a id="ckeditor5/latest/support/error-codes.html--error-filerepository-upload-wrong-status">  
####  
`[filerepository-upload-wrong-status](#ckeditor5/latest/support/error-codes.html--error-filerepository-upload-wrong-status)`  
You cannot call upload if the status is different than idle.
* <a id="ckeditor5/latest/support/error-codes.html--error-fileuploader-decoding-image-data-error">  
####  
`[fileuploader-decoding-image-data-error](#ckeditor5/latest/support/error-codes.html--error-fileuploader-decoding-image-data-error)`  
Problem with decoding Base64 image data.
* <a id="ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-api-address">  
####  
`[fileuploader-missing-api-address](#ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-api-address)`  
Api address must be provided as the third argument.
* <a id="ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-file">  
####  
`[fileuploader-missing-file](#ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-file)`  
File must be provided as the first argument.
* <a id="ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-token">  
####  
`[fileuploader-missing-token](#ckeditor5/latest/support/error-codes.html--error-fileuploader-missing-token)`  
Token must be provided as the second argument.
* <a id="ckeditor5/latest/support/error-codes.html--error-fileuploader-uploading-data-failed">  
####  
`[fileuploader-uploading-data-failed](#ckeditor5/latest/support/error-codes.html--error-fileuploader-uploading-data-failed)`  
Uploading file failed.
* <a id="ckeditor5/latest/support/error-codes.html--error-focustracker-add-element-already-exist">  
####  
`[focustracker-add-element-already-exist](#ckeditor5/latest/support/error-codes.html--error-focustracker-add-element-already-exist)`  
This element is already tracked by [FocusTracker](../api/module%5Futils%5Ffocustracker-FocusTracker.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-focustracker-add-view-missing-element">  
####  
`[focustracker-add-view-missing-element](#ckeditor5/latest/support/error-codes.html--error-focustracker-add-view-missing-element)`  
The [View](../api/module%5Fui%5Fview-View.html) added to the [FocusTracker](../api/module%5Futils%5Ffocustracker-FocusTracker.html) does not have an [element](../api/module%5Fui%5Fview-View.html#member-element). Make sure the view is [render](../api/module%5Fui%5Fview-View.html#function-render) before adding it to the focus tracker.
* <a id="ckeditor5/latest/support/error-codes.html--error-font-size-invalid-definition">  
####  
`[font-size-invalid-definition](#ckeditor5/latest/support/error-codes.html--error-font-size-invalid-definition)`  
Provided value as an option for [FontSize](../api/module%5Ffont%5Ffontsize-FontSize.html) seems to invalid.  
See valid examples described in the [plugin configuration](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-options).
* <a id="ckeditor5/latest/support/error-codes.html--error-font-size-invalid-use-of-named-presets">  
####  
`[font-size-invalid-use-of-named-presets](#ckeditor5/latest/support/error-codes.html--error-font-size-invalid-use-of-named-presets)`  
If [config.fontSize.supportAllValues](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-supportAllValues) is `true`, you need to use numerical values as font size options.  
See valid examples described in the [plugin configuration](../api/module%5Ffont%5Ffontconfig-FontSizeConfig.html#member-options).  
##### Parameters  
`presets : Array<string>`  
Invalid values.
* <a id="ckeditor5/latest/support/error-codes.html--error-footnotes-insertfootnotecommand-invalid-footnote-id">  
####  
`[footnotes-insertfootnotecommand-invalid-footnote-id](#ckeditor5/latest/support/error-codes.html--error-footnotes-insertfootnotecommand-invalid-footnote-id)`  
Insert footnote command executed with invalid footnote id.  
A valid footnote id is a non-empty string without spaces, that does not start with a digit.
* <a id="ckeditor5/latest/support/error-codes.html--error-format-painter-invalid-license-key">  
####  
`[format-painter-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-format-painter-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-format-painter-trial-license-key-reached-limit-changes">  
####  
`[format-painter-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-format-painter-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-html-embed-provide-sanitize-function">  
####  
`[html-embed-provide-sanitize-function](#ckeditor5/latest/support/error-codes.html--error-html-embed-provide-sanitize-function)`  
When using the HTML embed feature with the `config.htmlEmbed.showPreviews` set to `true`, it is strongly recommended to define a sanitize function that will clean up the input HTML in order to avoid XSS vulnerability.  
For a detailed overview, check the [HTML embed feature](#ckeditor5/latest/features/html/html-embed.html) documentation.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-block-plugin-required">  
####  
`[image-block-plugin-required](#ckeditor5/latest/support/error-codes.html--error-image-block-plugin-required)`  
The [ImageBlock](../api/module%5Fimage%5Fimageblock-ImageBlock.html) plugin must be enabled to allow inserting block images. See [type](../api/module%5Fimage%5Fimageconfig-ImageInsertConfig.html#member-type) to learn more.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-inline-plugin-required">  
####  
`[image-inline-plugin-required](#ckeditor5/latest/support/error-codes.html--error-image-inline-plugin-required)`  
The [ImageInline](../api/module%5Fimage%5Fimageinline-ImageInline.html) plugin must be enabled to allow inserting inline images. See [type](../api/module%5Fimage%5Fimageconfig-ImageInsertConfig.html#member-type) to learn more.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-insert-integration-exists">  
####  
`[image-insert-integration-exists](#ckeditor5/latest/support/error-codes.html--error-image-insert-integration-exists)`  
There are two insert-image integrations registered with the same name.  
Make sure that you do not load multiple asset manager plugins.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-insert-integrations-not-registered">  
####  
`[image-insert-integrations-not-registered](#ckeditor5/latest/support/error-codes.html--error-image-insert-integrations-not-registered)`  
The image insert feature requires integrations to be registered by separate features.  
The `insertImage` toolbar button requires integrations to be registered by other features. For example [ImageUpload](../api/module%5Fimage%5Fimageupload-ImageUpload.html), [ImageInsert](../api/module%5Fimage%5Fimageinsert-ImageInsert.html), [ImageInsertViaUrl](../api/module%5Fimage%5Fimageinsertviaurl-ImageInsertViaUrl.html), [CKBox](../api/module%5Fckbox%5Fckbox-CKBox.html)
* <a id="ckeditor5/latest/support/error-codes.html--error-image-insert-integrations-not-specified">  
####  
`[image-insert-integrations-not-specified](#ckeditor5/latest/support/error-codes.html--error-image-insert-integrations-not-specified)`  
The insert image feature requires a list of integrations to be provided in the editor configuration.  
The default list of integrations is `upload`, `assetManager`, `url`. Those integrations are included in the insert image dropdown if the given feature plugin is loaded. You should omit the `integrations`configuration key to use the default set or provide a selected list of integrations that should be used.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-insert-unknown-integration">  
####  
`[image-insert-unknown-integration](#ckeditor5/latest/support/error-codes.html--error-image-insert-unknown-integration)`  
The specified insert image integration name is unknown or the providing plugin is not loaded in the editor.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-style-configuration-definition-invalid">  
####  
`[image-style-configuration-definition-invalid](#ckeditor5/latest/support/error-codes.html--error-image-style-configuration-definition-invalid)`  
The image style definition provided in the configuration is invalid.  
Please make sure the definition implements properly one of the following:

  * [image style option definition](../api/module%5Fimage%5Fimageconfig-ImageStyleOptionDefinition.html),
  * [image style dropdown definition](../api/module%5Fimage%5Fimageconfig-ImageStyleDropdownDefinition.html)  
##### Parameters  
`info : object`  
The information about the invalid definition.
* <a id="ckeditor5/latest/support/error-codes.html--error-image-style-missing-dependency">  
####  
`[image-style-missing-dependency](#ckeditor5/latest/support/error-codes.html--error-image-style-missing-dependency)`  
In order to work correctly, each image style [option](../api/module%5Fimage%5Fimageconfig-ImageStyleOptionDefinition.html)requires specific model elements (also: types of images) to be supported by the editor.  
Model element names to which the image style option can be applied are defined in the [modelElements](../api/module%5Fimage%5Fimageconfig-ImageStyleOptionDefinition.html#member-modelElements) property of the style option definition.  
Explore the warning in the console to find out precisely which option is not supported and which editor plugins are missing. Make sure these plugins are loaded in your editor to get this image style option working.  
##### Parameters  
`style : string`  
The name of the unsupported option.  
`missingPlugins : Array<string>`  
The names of the plugins one of which has to be loaded for the particular option.
* <a id="ckeditor5/latest/support/error-codes.html--error-imageresizebuttons-missing-icon">  
####  
`[imageresizebuttons-missing-icon](#ckeditor5/latest/support/error-codes.html--error-imageresizebuttons-missing-icon)`  
When configuring [config.image.resizeOptions](../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-resizeOptions) for standalone buttons, a valid `icon` token must be set for each option.  
See all valid options described in the [plugin configuration](../api/module%5Fimage%5Fimageconfig-ImageResizeOption.html).  
##### Parameters  
`option : [ImageResizeOption](../api/module%5Fimage%5Fimageconfig-ImageResizeOption.html)`  
Invalid image resize option.
* <a id="ckeditor5/latest/support/error-codes.html--error-import-word-plugin-conversion-failed">  
####  
`[import-word-plugin-conversion-failed](#ckeditor5/latest/support/error-codes.html--error-import-word-plugin-conversion-failed)`  
An error occurred while importing the Word file. Check the response from the Cloud Services in the browser's network tab in the developer tools to find out the reason.
* <a id="ckeditor5/latest/support/error-codes.html--error-import-word-plugin-import-cancelled">  
####  
`[import-word-plugin-import-cancelled](#ckeditor5/latest/support/error-codes.html--error-import-word-plugin-import-cancelled)`  
The import procedure has been cancelled. The position, where the content of the Word file should be inserted, no longer exists, because the document structure has changed. Choose the position again and try to import the Word file again.
* <a id="ckeditor5/latest/support/error-codes.html--error-inlineannotations-attach-already-attached">  
####  
`[inlineannotations-attach-already-attached](#ckeditor5/latest/support/error-codes.html--error-inlineannotations-attach-already-attached)`  
Cannot attach the same annotation twice.
* <a id="ckeditor5/latest/support/error-codes.html--error-inlineannotations-detach-not-attached">  
####  
`[inlineannotations-detach-not-attached](#ckeditor5/latest/support/error-codes.html--error-inlineannotations-detach-not-attached)`  
Cannot detach a UI if it is not attached.
* <a id="ckeditor5/latest/support/error-codes.html--error-inlineannotations-not-allowed-with-context">  
####  
`[inlineannotations-not-allowed-with-context](#ckeditor5/latest/support/error-codes.html--error-inlineannotations-not-allowed-with-context)`  
The `InlineAnnotations` plugin is not allowed as a `Context` plugin. It can be used as an editor plugin only.
* <a id="ckeditor5/latest/support/error-codes.html--error-insert-bookmark-command-executed-with-invalid-name">  
####  
`[insert-bookmark-command-executed-with-invalid-name](#ckeditor5/latest/support/error-codes.html--error-insert-bookmark-command-executed-with-invalid-name)`  
Insert bookmark command can be executed only with a valid name.  
A valid bookmark name must be a non-empty string and must not contain any spaces.
* <a id="ckeditor5/latest/support/error-codes.html--error-insert-operation-position-invalid">  
####  
`[insert-operation-position-invalid](#ckeditor5/latest/support/error-codes.html--error-insert-operation-position-invalid)`  
Insertion position is invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-insertcontent-invalid-insertion-position">  
####  
`[insertcontent-invalid-insertion-position](#ckeditor5/latest/support/error-codes.html--error-insertcontent-invalid-insertion-position)`  
An internal error occurred when merging inserted content with its siblings. The insertion position should equal the merge position.  
If you encountered this error, report it back to the CKEditor 5 team with as many details as possible regarding the content being inserted and the insertion position.
* <a id="ckeditor5/latest/support/error-codes.html--error-insertcontent-wrong-position">  
####  
`[insertcontent-wrong-position](#ckeditor5/latest/support/error-codes.html--error-insertcontent-wrong-position)`  
Given node cannot be inserted on the given position.  
##### Parameters  
`node : [ModelNode](../api/module%5Fengine%5Fmodel%5Fnode-ModelNode.html)`  
Node to insert.  
`position : [ModelPosition](../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html)`  
Position to insert the node at.
* <a id="ckeditor5/latest/support/error-codes.html--error-insertobject-element-not-an-object">  
####  
`[insertobject-element-not-an-object](#ckeditor5/latest/support/error-codes.html--error-insertobject-element-not-an-object)`  
Tried to insert an element with [insertObject()](../api/module%5Fengine%5Fmodel%5Futils%5Finsertobject.html) function that is not defined as an object in schema. See [SchemaItemDefinition](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchemaItemDefinition.html#member-isObject). If you want to insert content that is not an object you might want to use [insertContent()](../api/module%5Fengine%5Fmodel%5Futils%5Finsertcontent.html) function.
* <a id="ckeditor5/latest/support/error-codes.html--error-insertobject-invalid-place-parameter-value">  
####  
`[insertobject-invalid-place-parameter-value](#ckeditor5/latest/support/error-codes.html--error-insertobject-invalid-place-parameter-value)`  
The unsupported `options.setSelection` parameter was passed to the [insertObject()](../api/module%5Fengine%5Fmodel%5Futils%5Finsertobject.html) function. Check the [insertObject()](../api/module%5Fengine%5Fmodel%5Futils%5Finsertobject.html) API documentation for allowed `options.setSelection` parameter values.
* <a id="ckeditor5/latest/support/error-codes.html--error-invalid-date-time-format">  
####  
`[invalid-date-time-format](#ckeditor5/latest/support/error-codes.html--error-invalid-date-time-format)`  
Date format must be a function.
* <a id="ckeditor5/latest/support/error-codes.html--error-invalid-license-key">  
####  
`[invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-invalid-license-key)`  
The license key provided is invalid. Please ensure that it is copied correctly from the [Customer Portal](http://portal.ckeditor.com). If the issue persists, please [contact our customer support](https://ckeditor.com/contact/).
* <a id="ckeditor5/latest/support/error-codes.html--error-keyboard-unknown-key">  
####  
`[keyboard-unknown-key](#ckeditor5/latest/support/error-codes.html--error-keyboard-unknown-key)`  
Unknown key name. Only key names included in the [keyCodes](../api/module%5Futils%5Fkeyboard.html#constant-keyCodes) can be used.  
##### Parameters  
`key : string`  
Ths specified key name.
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-development-limit">  
####  
`[license-key-development-limit](#ckeditor5/latest/support/error-codes.html--error-license-key-development-limit)`  
You have exceeded the operation limit for your development license key within the editor. Please restart the editor to continue using it. [Read more about license key types](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-domain-limit">  
####  
`[license-key-domain-limit](#ckeditor5/latest/support/error-codes.html--error-license-key-domain-limit)`  
The provided license does not allow the editor to run on this domain. Some license keys are restricted to local test environments only. For more details, please refer to the [license key type documentation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-evaluation-limit">  
####  
`[license-key-evaluation-limit](#ckeditor5/latest/support/error-codes.html--error-license-key-evaluation-limit)`  
You have exceeded the editor operation limit available for your evaluation license key. Please restart the editor to continue using it. [Read more about license key types](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-expired">  
####  
`[license-key-expired](#ckeditor5/latest/support/error-codes.html--error-license-key-expired)`  
Your license key has expired.  
If you used our free trial, you either need to switch to [open-source license](#ckeditor5/latest/getting-started/licensing/license-and-legal.html), or in case of a commercial plan, change the trial key to production key or development key. Switching from trial, you also need to align the editor configuration to the features available in your plan.  
If you already had one of our Cloud or Custom plans, please renew your license in the [Customer Portal](https://portal.ckeditor.com).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-feature-not-allowed">  
####  
`[license-key-feature-not-allowed](#ckeditor5/latest/support/error-codes.html--error-license-key-feature-not-allowed)`  
The feature you are trying to use is not permitted under your current license. Please check the available features on the [Customer Portal](https://portal.ckeditor.com) or [contact support](https://ckeditor.com/contact/) for more information.  
##### Parameters  
`featureName : String`  
The feature you tried to use.
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-invalid-distribution-channel">  
####  
`[license-key-invalid-distribution-channel](#ckeditor5/latest/support/error-codes.html--error-license-key-invalid-distribution-channel)`  
Your license does not allow the current distribution channel.  
These are the available distribution channels:

  * Self-hosted - the editor is installed via npm or from a ZIP package
  * Cloud - the editor is run from CDN  
The licenses available include:

  * GPL license for open-source users.
  * Commercial plans (Cloud or sales-assisted).  
The relation between distribution channels and licenses works as follows:

  * With the 'GPL' license key, you may use the editor installed via npm or a ZIP package (self-hosted).
  * With the CKEditor Cloud plans, you may use the editor via our CDN.
  * With the CKEditor Custom plans, depending on your plan details, you can use the editor via npm or a ZIP package (self-hosted) or Cloud (CDN).  
[Read more about distributions in the documentation](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html--key-terms). Please verify your installation or [contact support](https://ckeditor.com/contact/) for assistance. Should you need to migrate your installation from npm to CDN, please refer to our [dedicated migration guides](#ckeditor5/latest/updating/migrations/vanilla-js.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-lts-not-allowed">  
####  
`[license-key-lts-not-allowed](#ckeditor5/latest/support/error-codes.html--error-license-key-lts-not-allowed)`  
You are running [CKEditor 5 Long-term Support Edition (LTS)](https://ckeditor.com/ckeditor-5-lts/), but the provided license key does not include access to the LTS version, or the key is invalid.  
Please ensure that it is copied correctly from the [Customer Portal](http://portal.ckeditor.com/), and if the issue persists, please [contact our customer support](https://ckeditor.com/contact/).  
In case you intended to use the [LTS Edition](https://ckeditor.com/ckeditor-5-lts/), but have not yet made a purchase, please [contact our sales team](https://ckeditor.com/contact-sales/)  
If you did not intend to use LTS, please switch to non-LTS edition, for example, the [latest](#ckeditor5/latest/updating/guides/changelog.html) build.
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-missing">  
####  
`[license-key-missing](#ckeditor5/latest/support/error-codes.html--error-license-key-missing)`  
The `licenseKey` property is missing in the editor configuration.

  * If you are using the editor in a commercial setup, please provide your license key.
  * If you still need to acquire a key, please [contact us](https://ckeditor.com/contact/) or [create a free account with a 14 day premium features trial](https://portal.ckeditor.com/checkout?plan=free).
  * If you are using the editor under a GPL license or another license from our Open Source Initiative, use the 'GPL' license key instead.  
```  
ClassicEditor.create( {  
	attachTo: document.querySelector( '#editor' ),  
	licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.  
	// ... Other configuration options ...  
} ) ;  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-plugin-not-allowed">  
####  
`[license-key-plugin-not-allowed](#ckeditor5/latest/support/error-codes.html--error-license-key-plugin-not-allowed)`  
The plugin you are trying to use is not permitted under your current license. Please check the available features on the [Customer Portal](https://portal.ckeditor.com) or [contact support](https://ckeditor.com/contact/) for more information.  
##### Parameters  
`pluginName : String`  
The plugin you tried to load.
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-trial-limit">  
####  
`[license-key-trial-limit](#ckeditor5/latest/support/error-codes.html--error-license-key-trial-limit)`  
You have exceeded the editor operation limit for your trial license key. Please restart the editor to continue using it. [Read more about license key types](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--license-key-types).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-usage-limit">  
####  
`[license-key-usage-limit](#ckeditor5/latest/support/error-codes.html--error-license-key-usage-limit)`  
You have reached the usage limit of your license key. This can occur in the following situations:

  * You are on a free subscription without a connected payment method and have exceeded the allowed usage threshold.
  * Your account has overdue invoices and the grace period has ended.  
To extend the limit and restore access, please update the required details in the [Customer Portal](https://portal.ckeditor.com) or [contact our customer support](https://ckeditor.com/contact).
* <a id="ckeditor5/latest/support/error-codes.html--error-license-key-validation-endpoint-not-reachable">  
####  
`[license-key-validation-endpoint-not-reachable](#ckeditor5/latest/support/error-codes.html--error-license-key-validation-endpoint-not-reachable)`  
Your license key cannot be validated due to a network issue. Please ensure that your setup does not block requests to the validation endpoint.  
##### Parameters  
`url : string`  
The URL that was attempted to be reached for validation.
* <a id="ckeditor5/latest/support/error-codes.html--error-list-feature-conflict">  
####  
`[list-feature-conflict](#ckeditor5/latest/support/error-codes.html--error-list-feature-conflict)`  
The `List` feature cannot be loaded together with the `LegacyList` plugin.  
##### Parameters  
`conflictPlugin : string`  
Name of the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-locale-deprecated-language-property">  
####  
`[locale-deprecated-language-property](#ckeditor5/latest/support/error-codes.html--error-locale-deprecated-language-property)`  
The `Locale#language` property was deprecated and will be removed in the near future. Please use the [Locale#uiLanguage](../api/module%5Futils%5Flocale-Locale.html#member-uiLanguage) and [Locale#contentLanguage](../api/module%5Futils%5Flocale-Locale.html#member-contentLanguage) properties instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-mapping-model-offset-not-found">  
####  
`[mapping-model-offset-not-found](#ckeditor5/latest/support/error-codes.html--error-mapping-model-offset-not-found)`  
A model position could not be mapped to the view because specified model offset was too big and could not be found inside the mapped view element or view document fragment.
* <a id="ckeditor5/latest/support/error-codes.html--error-mapping-model-position-view-parent-not-found">  
####  
`[mapping-model-position-view-parent-not-found](#ckeditor5/latest/support/error-codes.html--error-mapping-model-position-view-parent-not-found)`  
A model position could not be mapped to the view because the parent of the model position does not have a mapped view element (might have not been converted yet or it has no converter).  
Make sure that the model element is correctly converted to the view.
* <a id="ckeditor5/latest/support/error-codes.html--error-marker-destroyed">  
####  
`[marker-destroyed](#ckeditor5/latest/support/error-codes.html--error-marker-destroyed)`  
Cannot use a [destroyed marker](../api/module%5Fengine%5Fmodel%5Fmarkercollection-MarkerCollection.html#function-destroy) instance.
* <a id="ckeditor5/latest/support/error-codes.html--error-markercollection-incorrect-marker-name">  
####  
`[markercollection-incorrect-marker-name](#ckeditor5/latest/support/error-codes.html--error-markercollection-incorrect-marker-name)`  
Marker name cannot contain the "," character.
* <a id="ckeditor5/latest/support/error-codes.html--error-markercollection-refresh-marker-not-exists">  
####  
`[markercollection-refresh-marker-not-exists](#ckeditor5/latest/support/error-codes.html--error-markercollection-refresh-marker-not-exists)`  
Marker with provided name does not exists.
* <a id="ckeditor5/latest/support/error-codes.html--error-matcher-pattern-deprecated-attributes-class-key">  
####  
`[matcher-pattern-deprecated-attributes-class-key](#ckeditor5/latest/support/error-codes.html--error-matcher-pattern-deprecated-attributes-class-key)`  
The key-value matcher pattern for `attributes` option is using deprecated `class` key.  
Use `classes` matcher pattern option instead:  
```  
// Instead of:  
const pattern = {  
	attributes: {  
		key1: 'value1',  
		key2: 'value2',  
		class: 'foobar'  
	}  
}  
// Use:  
const pattern = {  
	attributes: {  
		key1: 'value1',  
		key2: 'value2'  
	},  
	classes: 'foobar'  
}  
```  
Refer to the `#update-to-ckeditor-5-v2910` paragraph in the Update to v29.x guide in the [updating from older versions](#ckeditor5/latest/updating/guides/updating-from-older-versions.html) guide and the [MatcherPattern](../api/module%5Fengine%5Fview%5Fmatcher-MatcherPattern.html) documentation.  
##### Parameters  
`pattern : any`  
Pattern with missing properties.
* <a id="ckeditor5/latest/support/error-codes.html--error-matcher-pattern-deprecated-attributes-style-key">  
####  
`[matcher-pattern-deprecated-attributes-style-key](#ckeditor5/latest/support/error-codes.html--error-matcher-pattern-deprecated-attributes-style-key)`  
The key-value matcher pattern for `attributes` option is using deprecated `style` key.  
Use `styles` matcher pattern option instead:  
```  
// Instead of:  
const pattern = {  
	attributes: {  
		key1: 'value1',  
		key2: 'value2',  
		style: /^border.*$/  
	}  
}  
// Use:  
const pattern = {  
	attributes: {  
		key1: 'value1',  
		key2: 'value2'  
	},  
	styles: /^border.*$/  
}  
```  
Refer to the `#update-to-ckeditor-5-v2910` section in the `Update to v29.x` section in the [updating from older versions](#ckeditor5/latest/updating/guides/updating-from-older-versions.html) guide and [MatcherPattern](../api/module%5Fengine%5Fview%5Fmatcher-MatcherPattern.html) documentation.  
##### Parameters  
`pattern : any`  
Pattern with missing properties.
* <a id="ckeditor5/latest/support/error-codes.html--error-matcher-pattern-missing-key-or-value">  
####  
`[matcher-pattern-missing-key-or-value](#ckeditor5/latest/support/error-codes.html--error-matcher-pattern-missing-key-or-value)`  
The key-value matcher pattern is missing key or value. Both must be present. Refer the documentation: [MatcherPattern](../api/module%5Fengine%5Fview%5Fmatcher-MatcherPattern.html).  
##### Parameters  
`pattern : any`  
Pattern with missing properties.
* <a id="ckeditor5/latest/support/error-codes.html--error-media-embed-no-provider-name">  
####  
`[media-embed-no-provider-name](#ckeditor5/latest/support/error-codes.html--error-media-embed-no-provider-name)`  
One of the providers (or extra providers) specified in the media embed configuration has no name and will not be used by the editor. In order to get this media provider working, double check your editor configuration.
* <a id="ckeditor5/latest/support/error-codes.html--error-mention-feed-callback-error">  
####  
`[mention-feed-callback-error](#ckeditor5/latest/support/error-codes.html--error-mention-feed-callback-error)`  
The callback used for obtaining mention autocomplete feed thrown and error and the mention UI was hidden or not displayed at all.
* <a id="ckeditor5/latest/support/error-codes.html--error-mentioncommand-incorrect-id">  
####  
`[mentioncommand-incorrect-id](#ckeditor5/latest/support/error-codes.html--error-mentioncommand-incorrect-id)`  
The feed item ID must start with the marker character(s).  
Correct mention feed setting:  
```  
mentions: [  
	{  
		marker: '@',  
		feed: [ '@Ann', '@Barney', ... ]  
	}  
]  
```  
Incorrect mention feed setting:  
```  
mentions: [  
	{  
		marker: '@',  
		feed: [ 'Ann', 'Barney', ... ]  
	}  
]  
```  
See [MentionConfig](../api/module%5Fmention%5Fmentionconfig-MentionConfig.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-mentionconfig-incorrect-marker">  
####  
`[mentionconfig-incorrect-marker](#ckeditor5/latest/support/error-codes.html--error-mentionconfig-incorrect-marker)`  
The marker must be a single character.  
Correct markers: `'@'`, `'#'`.  
Incorrect markers: `'$$'`, `'[@'`.  
See [MentionConfig](../api/module%5Fmention%5Fmentionconfig-MentionConfig.html).  
##### Parameters  
`marker : string`  
Configured marker
* <a id="ckeditor5/latest/support/error-codes.html--error-menu-bar-component-unsupported">  
####  
`[menu-bar-component-unsupported](#ckeditor5/latest/support/error-codes.html--error-menu-bar-component-unsupported)`  
Adding unsupported components to the [MenuBarView](../api/module%5Fui%5Fmenubar%5Fmenubarview-MenuBarView.html) is not possible.  
A component should be either a [MenuBarMenuView](../api/module%5Fui%5Fmenubar%5Fmenubarmenuview-MenuBarMenuView.html) (sub-menu) or a [MenuBarMenuListItemButtonView](../api/module%5Fui%5Fmenubar%5Fmenubarmenulistitembuttonview-MenuBarMenuListItemButtonView.html) (button).  
##### Parameters  
`componentName : string`  
A name of the unsupported component used in the configuration.  
`componentView : [View](../api/module%5Fui%5Fview-View.html)`  
An unsupported component view.
* <a id="ckeditor5/latest/support/error-codes.html--error-menu-bar-item-could-not-be-removed">  
####  
`[menu-bar-item-could-not-be-removed](#ckeditor5/latest/support/error-codes.html--error-menu-bar-item-could-not-be-removed)`  
There was a problem processing the configuration of the menu bar. The item with the given name does could not be removed from the menu bar configuration.  
This warning usually shows up when the [Plugin](../api/module%5Fcore%5Fplugin-Plugin.html) which is supposed to provide a menu bar item has not been loaded or there is a typo in the [menu bar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar).  
##### Parameters  
`menuBarConfig : any`  
The full configuration of the menu bar.  
`itemName : any`  
The name of the item that was not removed from the menu bar.
* <a id="ckeditor5/latest/support/error-codes.html--error-menu-bar-item-could-not-be-removed">  
####  
`[menu-bar-item-could-not-be-removed](#ckeditor5/latest/support/error-codes.html--error-menu-bar-item-could-not-be-removed)`  
There was a problem processing the configuration of the menu bar. The configured item could not be added because the position it was supposed to be added to does not exist.  
This warning usually shows up when the [Plugin](../api/module%5Fcore%5Fplugin-Plugin.html) which is supposed to provide a menu bar item has not been loaded or there is a typo in the [menu bar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar).  
##### Parameters  
`menuBarConfig : object`  
The full configuration of the menu bar.  
`addedItemConfig : object`  
The name of the item that was not removed from the menu bar.
* <a id="ckeditor5/latest/support/error-codes.html--error-menu-bar-item-unavailable">  
####  
`[menu-bar-item-unavailable](#ckeditor5/latest/support/error-codes.html--error-menu-bar-item-unavailable)`  
There was a problem processing the configuration of the menu bar. The item with the given name does not exist so it was omitted when rendering the menu bar.  
This warning usually shows up when the [Plugin](../api/module%5Fcore%5Fplugin-Plugin.html) which is supposed to provide a menu bar item has not been loaded or there is a typo in the [menu bar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar).  
Make sure the plugin responsible for this menu bar item is loaded and the menu bar configuration is correct, e.g. [BoldUI](../api/module%5Fbasic-styles%5Fbold%5Fboldui-BoldUI.html) is loaded for the `'menuBar:bold'`menu bar item.  
##### Parameters  
`menuBarConfig : object`  
The full configuration of the menu bar.  
`parentMenuConfig : object`  
The config of the menu the unavailable component was defined in.  
`componentName : string`  
The name of the unavailable component.
* <a id="ckeditor5/latest/support/error-codes.html--error-menu-bar-menu-empty">  
####  
`[menu-bar-menu-empty](#ckeditor5/latest/support/error-codes.html--error-menu-bar-menu-empty)`  
There was a problem processing the configuration of the menu bar. One of the menus is empty so it was omitted when rendering the menu bar.  
This warning usually shows up when some [plugins](../api/module%5Fcore%5Fplugin-Plugin.html) responsible for providing menu bar items have not been loaded and the [menu bar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-menuBar) was not updated.  
Make sure all necessary editor plugins are loaded and/or update the menu bar configuration to account for the missing menu items.  
##### Parameters  
`menuBarConfig : object`  
The full configuration of the menu bar.  
`emptyMenuConfig : object`  
The definition of the menu that has no child items.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-data-set-not-found">  
####  
`[merge-fields-data-set-not-found](#ckeditor5/latest/support/error-codes.html--error-merge-fields-data-set-not-found)`  
The requested data set was not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-data-set-id">  
####  
`[merge-fields-duplicate-data-set-id](#ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-data-set-id)`  
Data set ids must be unique.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-group-id">  
####  
`[merge-fields-duplicate-group-id](#ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-group-id)`  
Merge field group ids must be unique.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-merge-field-id">  
####  
`[merge-fields-duplicate-merge-field-id](#ckeditor5/latest/support/error-codes.html--error-merge-fields-duplicate-merge-field-id)`  
Merge field ids must be unique.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-id">  
####  
`[merge-fields-invalid-id](#ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-id)`  
Merge field ids can contain only alphanumeric characters, dots, underscores, and hyphens.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-prefix-or-suffix">  
####  
`[merge-fields-invalid-prefix-or-suffix](#ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-prefix-or-suffix)`  
The merge field prefix and suffix can only contain the following characters: `` '"`!#%:;=@{}~$()*+/?[\]^| ``.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-preview-mode-set">  
####  
`[merge-fields-invalid-preview-mode-set](#ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-preview-mode-set)`  
The preview mode that was tried to be set was not available. See the [preview modes configuration](../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-previewModes)for more information.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-preview-modes-configuration">  
####  
`[merge-fields-invalid-preview-modes-configuration](#ckeditor5/latest/support/error-codes.html--error-merge-fields-invalid-preview-modes-configuration)`  
Invalid preview modes definition. It should be a non-empty array, with one or more of the following values: '$labels', '$defaultValues' and '$dataSets'.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-prefix-and-suffix-must-differ">  
####  
`[merge-fields-prefix-and-suffix-must-differ](#ckeditor5/latest/support/error-codes.html--error-merge-fields-prefix-and-suffix-must-differ)`  
Merge field prefix and suffix must be different.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-prefix-or-suffix-too-long">  
####  
`[merge-fields-prefix-or-suffix-too-long](#ckeditor5/latest/support/error-codes.html--error-merge-fields-prefix-or-suffix-too-long)`  
The merge field prefix and suffix cannot be longer than 8 characters.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-fields-provide-sanitize-function">  
####  
`[merge-fields-provide-sanitize-function](#ckeditor5/latest/support/error-codes.html--error-merge-fields-provide-sanitize-function)`  
When using the merge fields feature with the `config.mergeFields.previewHtmlValues` set to `true`, it is strongly recommended to define a sanitize function that will clean up the input HTML in order to avoid XSS vulnerability.  
For a detailed overview, check the [Merge fields feature](#ckeditor5/latest/features/merge-fields.html--using-html-tags-in-merge-fields-values)documentation.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-operation-how-many-invalid">  
####  
`[merge-operation-how-many-invalid](#ckeditor5/latest/support/error-codes.html--error-merge-operation-how-many-invalid)`  
Merge operation specifies wrong number of nodes to move.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-operation-source-position-invalid">  
####  
`[merge-operation-source-position-invalid](#ckeditor5/latest/support/error-codes.html--error-merge-operation-source-position-invalid)`  
Merge source position is invalid. The element to be merged must have a parent node.
* <a id="ckeditor5/latest/support/error-codes.html--error-merge-operation-target-position-invalid">  
####  
`[merge-operation-target-position-invalid](#ckeditor5/latest/support/error-codes.html--error-merge-operation-target-position-invalid)`  
Merge target position is invalid. The element to be merged must have a parent node.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-createpositionat-offset-required">  
####  
`[model-createpositionat-offset-required](#ckeditor5/latest/support/error-codes.html--error-model-createpositionat-offset-required)`  
[Model#createPositionAt()](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-createPositionAt)requires the offset to be specified when the first parameter is a model item.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-document-createroot-name-exists">  
####  
`[model-document-createroot-name-exists](#ckeditor5/latest/support/error-codes.html--error-model-document-createroot-name-exists)`  
A root with the specified name already exists.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-document-history-addoperation-incorrect-version">  
####  
`[model-document-history-addoperation-incorrect-version](#ckeditor5/latest/support/error-codes.html--error-model-document-history-addoperation-incorrect-version)`  
Only operations with matching versions can be added to the history.  
##### Parameters  
`operation : [Operation](../api/module%5Fengine%5Fmodel%5Foperation%5Foperation-Operation.html)`  
The current operation.  
`historyVersion : number`  
The current document history version.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-liveposition-root-not-rootelement">  
####  
`[model-liveposition-root-not-rootelement](#ckeditor5/latest/support/error-codes.html--error-model-liveposition-root-not-rootelement)`  
LivePosition's root has to be an instance of ModelRootElement.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-nodelist-index-out-of-bounds">  
####  
`[model-nodelist-index-out-of-bounds](#ckeditor5/latest/support/error-codes.html--error-model-nodelist-index-out-of-bounds)`  
Given index cannot be found in the node list.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-nodelist-insertnodes-not-node">  
####  
`[model-nodelist-insertnodes-not-node](#ckeditor5/latest/support/error-codes.html--error-model-nodelist-insertnodes-not-node)`  
Trying to insert an object which is not a Node instance.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-nodelist-offset-out-of-bounds">  
####  
`[model-nodelist-offset-out-of-bounds](#ckeditor5/latest/support/error-codes.html--error-model-nodelist-offset-out-of-bounds)`  
Given offset cannot be found in the node list.  
##### Parameters  
`offset : number`  
The offset value.  
`nodeList : [ModelNodeList](../api/module%5Fengine%5Fmodel%5Fnodelist-ModelNodeList.html)`  
Stringified node list.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-after-root">  
####  
`[model-position-after-root](#ckeditor5/latest/support/error-codes.html--error-model-position-after-root)`  
You cannot make a position after a root element.  
##### Parameters  
`root : [ModelRootElement](../api/module%5Fengine%5Fmodel%5Frootelement-ModelRootElement.html)`  
The root element..
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-before-root">  
####  
`[model-position-before-root](#ckeditor5/latest/support/error-codes.html--error-model-position-before-root)`  
You cannot make a position before a root element.  
##### Parameters  
`root : [ModelRootElement](../api/module%5Fengine%5Fmodel%5Frootelement-ModelRootElement.html)`  
The root element..
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-fromjson-no-root">  
####  
`[model-position-fromjson-no-root](#ckeditor5/latest/support/error-codes.html--error-model-position-fromjson-no-root)`  
Cannot create position for document. Root with specified name does not exist.  
##### Parameters  
`rootName : string`  
The root name.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-parent-incorrect">  
####  
`[model-position-parent-incorrect](#ckeditor5/latest/support/error-codes.html--error-model-position-parent-incorrect)`  
Position parent have to be a model element or model document fragment.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-path-incorrect">  
####  
`[model-position-path-incorrect](#ckeditor5/latest/support/error-codes.html--error-model-position-path-incorrect)`  
The position's path is incorrect. This means that a position does not point to a correct place in the tree and hence, some of its methods and getters cannot work correctly.

**Note**: Unlike DOM and view positions, in the model, the [position's parent](../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html#member-parent) is always an element or a document fragment. The last offset in the [position's path](../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html#member-path) is the point in this element where this position points.  
Read more about model positions and offsets in the [Editing engine architecture](#ckeditor5/latest/framework/architecture/editing-engine.html--indexes-and-offsets) guide.  
##### Parameters  
`position : [ModelPosition](../api/module%5Fengine%5Fmodel%5Fposition-ModelPosition.html)`  
The incorrect position.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-path-incorrect-format">  
####  
`[model-position-path-incorrect-format](#ckeditor5/latest/support/error-codes.html--error-model-position-path-incorrect-format)`  
Position path must be an array with at least one item.  
##### Parameters  
`path : Array<number>`  
A path to the position.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-position-root-invalid">  
####  
`[model-position-root-invalid](#ckeditor5/latest/support/error-codes.html--error-model-position-root-invalid)`  
Position root is invalid.  
Positions can only be anchored in elements or document fragments.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-selection-range-intersects">  
####  
`[model-selection-range-intersects](#ckeditor5/latest/support/error-codes.html--error-model-selection-range-intersects)`  
Trying to add a range that intersects with another range in the selection.  
##### Parameters  
`addedRange : [ModelRange](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html)`  
Range that was added to the selection.  
`intersectingRange : [ModelRange](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html)`  
Range in the selection that intersects with `addedRange`.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-selection-set-ranges-not-range">  
####  
`[model-selection-set-ranges-not-range](#ckeditor5/latest/support/error-codes.html--error-model-selection-set-ranges-not-range)`  
Selection range set to an object that is not an instance of [ModelRange](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html).  
Only [ModelRange](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html) instances can be used to set a selection. Common mistakes leading to this error are:

  * using DOM `Range` object,
  * incorrect CKEditor 5 installation with multiple `ckeditor5-engine` packages having different versions.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-selection-setfocus-no-ranges">  
####  
`[model-selection-setfocus-no-ranges](#ckeditor5/latest/support/error-codes.html--error-model-selection-setfocus-no-ranges)`  
Cannot set selection focus if there are no ranges in selection.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-selection-setto-not-selectable">  
####  
`[model-selection-setto-not-selectable](#ckeditor5/latest/support/error-codes.html--error-model-selection-setto-not-selectable)`  
Cannot set the selection to the given place.  
Invalid parameters were specified when setting the selection. Common issues:

  * A [ModelTextProxy](../api/module%5Fengine%5Fmodel%5Ftextproxy-ModelTextProxy.html) instance was passed instead of a real [ModelText](../api/module%5Fengine%5Fmodel%5Ftext-ModelText.html).
  * View nodes were passed instead of model nodes.
  * `null`/`undefined` was passed.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-selection-setto-required-second-parameter">  
####  
`[model-selection-setto-required-second-parameter](#ckeditor5/latest/support/error-codes.html--error-model-selection-setto-required-second-parameter)`  
selection.setTo requires the second parameter when the first parameter is a node.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-textproxy-wrong-length">  
####  
`[model-textproxy-wrong-length](#ckeditor5/latest/support/error-codes.html--error-model-textproxy-wrong-length)`  
Given `length` value is incorrect.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-textproxy-wrong-offsetintext">  
####  
`[model-textproxy-wrong-offsetintext](#ckeditor5/latest/support/error-codes.html--error-model-textproxy-wrong-offsetintext)`  
Given `offsetInText` value is incorrect.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-tree-walker-no-start-position">  
####  
`[model-tree-walker-no-start-position](#ckeditor5/latest/support/error-codes.html--error-model-tree-walker-no-start-position)`  
Neither boundaries nor starting position of a `TreeWalker` have been defined.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-tree-walker-unknown-direction">  
####  
`[model-tree-walker-unknown-direction](#ckeditor5/latest/support/error-codes.html--error-model-tree-walker-unknown-direction)`  
Only `backward` and `forward` direction allowed.
* <a id="ckeditor5/latest/support/error-codes.html--error-model-writer-insert-forbidden-move">  
####  
`[model-writer-insert-forbidden-move](#ckeditor5/latest/support/error-codes.html--error-model-writer-insert-forbidden-move)`  
Cannot move a node from a document to a different tree. It is forbidden to move a node that was already in a document outside of it.
* <a id="ckeditor5/latest/support/error-codes.html--error-move-operation-node-into-itself">  
####  
`[move-operation-node-into-itself](#ckeditor5/latest/support/error-codes.html--error-move-operation-node-into-itself)`  
Trying to move a range of nodes into one of nodes from that range.
* <a id="ckeditor5/latest/support/error-codes.html--error-move-operation-nodes-do-not-exist">  
####  
`[move-operation-nodes-do-not-exist](#ckeditor5/latest/support/error-codes.html--error-move-operation-nodes-do-not-exist)`  
The nodes which should be moved do not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-move-operation-range-into-itself">  
####  
`[move-operation-range-into-itself](#ckeditor5/latest/support/error-codes.html--error-move-operation-range-into-itself)`  
Trying to move a range of nodes into the middle of that range.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-level-list-invalid-license-key">  
####  
`[multi-level-list-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-multi-level-list-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-level-list-trial-license-key-reached-limit-changes">  
####  
`[multi-level-list-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-multi-level-list-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-cannot-disable-graveyard-root">  
####  
`[multi-root-editor-cannot-disable-graveyard-root](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-cannot-disable-graveyard-root)`  
You cannot disable the `$graveyard` root.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-load-root-already-loaded">  
####  
`[multi-root-editor-load-root-already-loaded](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-load-root-already-loaded)`  
The root to load was already loaded before. The `loadRoot()` call has no effect.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-load-root-no-root">  
####  
`[multi-root-editor-load-root-no-root](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-load-root-no-root)`  
The root to load does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-conflict">  
####  
`[multi-root-editor-root-attributes-conflict](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-conflict)`  
Trying to set attributes using deprecated `config.rootsAttributes` on a root that has already defined attributes using `config.roots.<rootName>.modelAttributes`.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-no-root">  
####  
`[multi-root-editor-root-attributes-no-root](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-no-root)`  
Trying to set attributes on a non-existing root.  
Roots specified in legacy `config.rootsAttributes` do not match initial editor roots. Use `config.roots.<rootName>.modelAttributes` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-no-root">  
####  
`[multi-root-editor-root-attributes-no-root](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-attributes-no-root)`  
Trying to set attributes on a non-existing root.  
Roots specified in `config.rootsAttributes` do not match initial editor roots.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-deprecated-config-lazy-roots">  
####  
`[multi-root-editor-root-deprecated-config-lazy-roots](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-deprecated-config-lazy-roots)`  
Using deprecated `config.lazyRoots` configuration option. Use `config.roots.<rootName>.lazyLoad` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-initial-data-mismatch">  
####  
`[multi-root-editor-root-initial-data-mismatch](#ckeditor5/latest/support/error-codes.html--error-multi-root-editor-root-initial-data-mismatch)`  
Editor roots do not match the [initialData configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData).  
This may happen for one of the two reasons:

  * Configuration error. The `sourceElementsOrData` parameter in [MultiRootEditor.create()](../api/module%5Feditor-multi-root%5Fmultirooteditor-MultiRootEditor.html#static-function-create) contains different roots than [initialData configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData).
  * As the editor was initialized, the [initialData](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData)configuration value or the state of the editor roots has been changed.
* <a id="ckeditor5/latest/support/error-codes.html--error-narrowsidebar-attach-already-attached">  
####  
`[narrowsidebar-attach-already-attached](#ckeditor5/latest/support/error-codes.html--error-narrowsidebar-attach-already-attached)`  
Cannot attach narrow sidebar twice.
* <a id="ckeditor5/latest/support/error-codes.html--error-narrowsidebar-detach-not-attached">  
####  
`[narrowsidebar-detach-not-attached](#ckeditor5/latest/support/error-codes.html--error-narrowsidebar-detach-not-attached)`  
Cannot detach not attached sidebar.
* <a id="ckeditor5/latest/support/error-codes.html--error-no-operations-provided">  
####  
`[no-operations-provided](#ckeditor5/latest/support/error-codes.html--error-no-operations-provided)`  
The compressor cannot compress operations because no operation was provided.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-duplicate-properties">  
####  
`[observable-bind-duplicate-properties](#ckeditor5/latest/support/error-codes.html--error-observable-bind-duplicate-properties)`  
Properties must be unique.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-rebind">  
####  
`[observable-bind-rebind](#ckeditor5/latest/support/error-codes.html--error-observable-bind-rebind)`  
Cannot bind the same property more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-to-extra-callback">  
####  
`[observable-bind-to-extra-callback](#ckeditor5/latest/support/error-codes.html--error-observable-bind-to-extra-callback)`  
Cannot bind multiple properties and use a callback in one binding.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-to-many-not-one-binding">  
####  
`[observable-bind-to-many-not-one-binding](#ckeditor5/latest/support/error-codes.html--error-observable-bind-to-many-not-one-binding)`  
Binding one attribute to many observables only possible with one attribute.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-to-no-callback">  
####  
`[observable-bind-to-no-callback](#ckeditor5/latest/support/error-codes.html--error-observable-bind-to-no-callback)`  
Binding multiple observables only possible with callback.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-to-parse-error">  
####  
`[observable-bind-to-parse-error](#ckeditor5/latest/support/error-codes.html--error-observable-bind-to-parse-error)`  
Invalid argument syntax in `to()`.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-to-properties-length">  
####  
`[observable-bind-to-properties-length](#ckeditor5/latest/support/error-codes.html--error-observable-bind-to-properties-length)`  
The number of properties must match.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-bind-wrong-properties">  
####  
`[observable-bind-wrong-properties](#ckeditor5/latest/support/error-codes.html--error-observable-bind-wrong-properties)`  
All properties must be strings.
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-set-cannot-override">  
####  
`[observable-set-cannot-override](#ckeditor5/latest/support/error-codes.html--error-observable-set-cannot-override)`  
Cannot override an existing property.  
This error is thrown when trying to [set](../api/module%5Futils%5Fobservablemixin-Observable.html#function-set:KEY%5FVALUE) a property with a name of an already existing property. For example:  
```  
let observable = new Model();  
observable.property = 1;  
observable.set( 'property', 2 );			// throws  
observable.set( 'property', 1 );  
observable.set( 'property', 2 );			// ok, because this is an existing property.  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-observable-unbind-wrong-properties">  
####  
`[observable-unbind-wrong-properties](#ckeditor5/latest/support/error-codes.html--error-observable-unbind-wrong-properties)`  
Properties must be strings.
* <a id="ckeditor5/latest/support/error-codes.html--error-observablemixin-cannot-decorate-undefined">  
####  
`[observablemixin-cannot-decorate-undefined](#ckeditor5/latest/support/error-codes.html--error-observablemixin-cannot-decorate-undefined)`  
Cannot decorate an undefined method.  
##### Parameters  
`object : object`  
The object which method should be decorated.  
`methodName : string`  
Name of the method which does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-operation-utils-move-range-not-flat">  
####  
`[operation-utils-move-range-not-flat](#ckeditor5/latest/support/error-codes.html--error-operation-utils-move-range-not-flat)`  
Trying to move a range which starts and ends in different element.
* <a id="ckeditor5/latest/support/error-codes.html--error-operation-utils-remove-range-not-flat">  
####  
`[operation-utils-remove-range-not-flat](#ckeditor5/latest/support/error-codes.html--error-operation-utils-remove-range-not-flat)`  
Trying to remove a range which starts and ends in different element.
* <a id="ckeditor5/latest/support/error-codes.html--error-pagination-config-not-found">  
####  
`[pagination-config-not-found](#ckeditor5/latest/support/error-codes.html--error-pagination-config-not-found)`  
The configuration required by the pagination plugin is missing. Follow the instructions provided in [Pagination feature documentation](#ckeditor5/latest/features/pagination/pagination.html--configuration)to initialize the plugin properly.  
##### Parameters  
`config : [EditorConfig](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html)`  
Configuration of the editor.
* <a id="ckeditor5/latest/support/error-codes.html--error-pagination-invalid-license-key">  
####  
`[pagination-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-pagination-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-pagination-trial-license-key-reached-limit-changes">  
####  
`[pagination-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-pagination-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-paste-from-office-enhanced-invalid-license-key">  
####  
`[paste-from-office-enhanced-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-paste-from-office-enhanced-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-paste-from-office-enhanced-trial-license-key-reached-limit-changes">  
####  
`[paste-from-office-enhanced-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-paste-from-office-enhanced-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-pendingactions-add-invalid-message">  
####  
`[pendingactions-add-invalid-message](#ckeditor5/latest/support/error-codes.html--error-pendingactions-add-invalid-message)`  
The message must be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-permissions-set-permissions-invalid-channel-id">  
####  
`[permissions-set-permissions-invalid-channel-id](#ckeditor5/latest/support/error-codes.html--error-permissions-set-permissions-invalid-channel-id)`  
Trying to set permissions for a `channelId` that does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugin-load  
%2A">  
####  
`[plugin-load *](#ckeditor5/latest/support/error-codes.html--error-plugin-load%2A)`  
The CKEditor error class.  
You should throw `CKEditorError` when:

  * An unexpected situation occurred and the editor (most probably) will not work properly. Such exception will be handled by the [watchdog](../api/module%5Fwatchdog%5Fwatchdog-Watchdog.html) (if it is integrated),
  * If the editor is incorrectly integrated or the editor API is used in the wrong way. This way you will give feedback to the developer as soon as possible. Keep in mind that for common integration issues which should not stop editor initialization (like missing upload adapter, wrong name of a toolbar component) we use [logWarning()](../api/module%5Futils%5Fckeditorerror.html#function-logWarning) and [logError()](../api/module%5Futils%5Fckeditorerror.html#function-logError)to improve developers experience and let them see the a working editor as soon as possible.  
```  
/**
 * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
 *
 *  
```  
##### Parameters  
`pluginName : any`  
The name of the plugin that could not be loaded. \*  
`moduleName : any`  
The name of the module which tried to load this plugin. \*/ throw new CKEditorError( 'plugin-load', { pluginName: 'foo', moduleName: 'bar' } );  
```  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-documentlist">  
####  
`[plugin-obsolete-documentlist](#ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-documentlist)`  
The `DocumentList` plugin is obsolete. Use `List` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-documentlistproperties">  
####  
`[plugin-obsolete-documentlistproperties](#ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-documentlistproperties)`  
The `DocumentListProperties` plugin is obsolete. Use `ListProperties` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-tododocumentlist">  
####  
`[plugin-obsolete-tododocumentlist](#ckeditor5/latest/support/error-codes.html--error-plugin-obsolete-tododocumentlist)`  
The `TodoDocumentList` plugin is obsolete. Use `TodoList` instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-context-required">  
####  
`[plugincollection-context-required](#ckeditor5/latest/support/error-codes.html--error-plugincollection-context-required)`  
If a plugin is a context plugin, all plugins it requires should also be context plugins instead of plugins. In other words, if one plugin can be used in the context, all its requirements should also be ready to be used in the context. Note that the context provides only a part of the API provided by the editor. If one plugin needs a full editor API, all plugins which require it are considered as plugins that need a full editor API.  
##### Parameters  
`plugin : string`  
The name of the required plugin.  
`requiredBy : string`  
The name of the parent plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-cannot-have-dependencies">  
####  
`[plugincollection-plugin-for-replacing-cannot-have-dependencies](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-cannot-have-dependencies)`  
The plugin replacing an existing plugin cannot depend on other plugins.  
##### Parameters  
`pluginName : string`  
The name of the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-not-exist">  
####  
`[plugincollection-plugin-for-replacing-not-exist](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-not-exist)`  
The replaced plugin does not exist in the [available plugins](../api/module%5Fcore%5Fplugincollection-PluginCollection.html) collection.  
##### Parameters  
`pluginName : string`  
The name of the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-not-loaded">  
####  
`[plugincollection-plugin-for-replacing-not-loaded](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-for-replacing-not-loaded)`  
The replaced plugin will not be loaded so it cannot be replaced.  
##### Parameters  
`pluginName : string`  
The name of the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-invalid-constructor">  
####  
`[plugincollection-plugin-invalid-constructor](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-invalid-constructor)`  
The provided class constructor is not a plugin.  
This error is usually caused by passing an editor, context, or command constructor in the `config.plugins` array.  
##### Parameters  
`name : String`  
The name of the provided constructor.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-name-conflict">  
####  
`[plugincollection-plugin-name-conflict](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-name-conflict)`  
Two plugins with the same [pluginName](../api/module%5Fcore%5Fplugin-PluginStaticMembers.html#member-pluginName) were loaded. This will lead to runtime conflicts between these plugins.  
In practice, this warning usually means that new plugins were added to an existing CKEditor 5 build. Plugins should always be added to a source version of the editor (`@ckeditor/ckeditor5-editor-*`), not to an editor imported from one of the `@ckeditor/ckeditor5-build-*` packages.  
Check your import paths and the list of plugins passed to [Editor.create()](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-function-create)or specified in [Editor.builtinPlugins](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-member-builtinPlugins).  
Predefined builds are a deprecated solution and we strongly advise [migrating to new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html).  
The second option is that your `node_modules/` directory contains duplicated versions of the same CKEditor 5 packages. Normally, on clean installations, npm deduplicates packages in `node_modules/`, so it may be enough to call `rm -rf node_modules && npm i`. However, if you installed conflicting versions of some packages, their dependencies may need to be installed in more than one version which may lead to this warning.  
Technically speaking, this error occurs because after adding a plugin to an existing editor build the dependencies of this plugin are being duplicated. They are already built into that editor build and now get added for the second time as dependencies of the plugin you are installing.  
##### Parameters  
`pluginName : string`  
The duplicated plugin name.  
`plugin1 : [PluginConstructor](../api/module%5Fcore%5Fplugin-PluginConstructor.html)`  
The first plugin constructor.  
`plugin2 : [PluginConstructor](../api/module%5Fcore%5Fplugin-PluginConstructor.html)`  
The second plugin constructor.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-not-found">  
####  
`[plugincollection-plugin-not-found](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-not-found)`  
A plugin is not available and could not be loaded.  
Plugin classes (constructors) need to be provided to the editor before they can be loaded by name. This is usually done in the now deprecated CKEditor 5 builds by setting the [builtinPlugins](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-member-builtinPlugins) property.

**If you see this warning when using one of the deprecated CKEditor 5 Builds**, it means that you tried to enable a plugin that was not included in that build. This may be due to a typo in the plugin name or simply because that plugin was not a part of this build.

**Predefined builds are no longer supported and you need to [migrate to new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html)**.

**If you see this warning when using one of the editor creators directly** (not a build), then it means that you tried loading plugins by name. However, unlike CKEditor 4, CKEditor 5 does not implement a "plugin loader". This means that CKEditor 5 does not know where to load the plugin modules from. Therefore, you need to provide each plugin through a reference (as a constructor function). Check out the examples in the [Quick start](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html) guide.  
##### Parameters  
`plugin : string`  
The name of the plugin which could not be loaded.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-not-loaded">  
####  
`[plugincollection-plugin-not-loaded](#ckeditor5/latest/support/error-codes.html--error-plugincollection-plugin-not-loaded)`  
The plugin is not loaded and could not be obtained.  
Plugin classes (constructors) need to be provided to the editor and must be loaded before they can be obtained from the plugin collection.

**Note**: You can use `[editor.plugins.has()](../api/module%5Fcore%5Fplugincollection-PluginCollection.html#function-has)`to check if a plugin was loaded.  
##### Parameters  
`plugin : string`  
The name of the plugin which is not loaded.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-replace-plugin-invalid-type">  
####  
`[plugincollection-replace-plugin-invalid-type](#ckeditor5/latest/support/error-codes.html--error-plugincollection-replace-plugin-invalid-type)`  
The plugin replacing an existing plugin must be a function.  
##### Parameters  
`pluginItem : never`  
The plugin item.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-replace-plugin-missing-name">  
####  
`[plugincollection-replace-plugin-missing-name](#ckeditor5/latest/support/error-codes.html--error-plugincollection-replace-plugin-missing-name)`  
The plugin replacing an existing plugin must have a name.  
##### Parameters  
`pluginItem : [PluginConstructor](../api/module%5Fcore%5Fplugin-PluginConstructor.html)`  
The plugin item.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-replaced-plugin-cannot-have-dependencies">  
####  
`[plugincollection-replaced-plugin-cannot-have-dependencies](#ckeditor5/latest/support/error-codes.html--error-plugincollection-replaced-plugin-cannot-have-dependencies)`  
The replaced plugin cannot depend on other plugins.  
##### Parameters  
`pluginName : string`  
The name of the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-required">  
####  
`[plugincollection-required](#ckeditor5/latest/support/error-codes.html--error-plugincollection-required)`  
Cannot load a plugin because one of its dependencies is listed in the `removePlugins` option.  
##### Parameters  
`plugin : string`  
The name of the required plugin.  
`requiredBy : string`  
The name of the parent plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-plugincollection-soft-required">  
####  
`[plugincollection-soft-required](#ckeditor5/latest/support/error-codes.html--error-plugincollection-soft-required)`  
A required "soft" dependency was not found on the plugin list.  
When configuring the editor, either prior to building (via [Editor.builtinPlugins](../api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-member-builtinPlugins)) or when creating a new instance of the editor (e.g. via [config.plugins](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-plugins)), you need to provide some of the dependencies for other plugins that you used.  
This error is thrown when one of these dependencies was not provided. The name of the missing plugin can be found in `missingPlugin` and the plugin that required it in `requiredBy`.  
In order to resolve it, you need to import the missing plugin and add it to the current list of plugins (`Editor.builtinPlugins` or `config.plugins`/`config.extraPlugins`).  
Soft requirements were introduced in version 26.0.0\. If you happen to stumble upon this error when upgrading to version 26.0.0, read also the `Update to v26.x` section in the [updating from older versions](#ckeditor5/latest/updating/guides/updating-from-older-versions.html) guide.  
##### Parameters  
`missingPlugin : string`  
The name of the required plugin.  
`requiredBy : string`  
The name of the plugin that requires the other plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-presencelist-collapseat-invalid-format">  
####  
`[presencelist-collapseat-invalid-format](#ckeditor5/latest/support/error-codes.html--error-presencelist-collapseat-invalid-format)`  
The [config.presenceList.collapseAt](../api/module%5Freal-time-collaboration%5Fconfig-RtcPresenceListConfig.html#member-collapseAt)configuration value must be a number greater than 0.
* <a id="ckeditor5/latest/support/error-codes.html--error-presencelist-missing-container">  
####  
`[presencelist-missing-container](#ckeditor5/latest/support/error-codes.html--error-presencelist-missing-container)`  
Missing container element for the presence list. Please make sure [config.presenceList.container](../api/module%5Freal-time-collaboration%5Fconfig-RtcPresenceListConfig.html#member-container)is set and refers to an existing DOM element.
* <a id="ckeditor5/latest/support/error-codes.html--error-protobuffactory-cannot-get-descriptor-before-build">  
####  
`[protobuffactory-cannot-get-descriptor-before-build](#ckeditor5/latest/support/error-codes.html--error-protobuffactory-cannot-get-descriptor-before-build)`  
Cannot get a descriptor before building `ProtobufFactory`.
* <a id="ckeditor5/latest/support/error-codes.html--error-range-create-from-ranges-empty-array">  
####  
`[range-create-from-ranges-empty-array](#ckeditor5/latest/support/error-codes.html--error-range-create-from-ranges-empty-array)`  
At least one range has to be passed to [Range.\_createFromRanges()](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html#static-function-%5FcreateFromRanges).
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-editor-setdata-and-editor-data-set-are-forbidden-in-real-time-collaboration">  
####  
`[realtimecollaborationclient-editor-setdata-and-editor-data-set-are-forbidden-in-real-time-collaboration](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-editor-setdata-and-editor-data-set-are-forbidden-in-real-time-collaboration)`  
Trying to use `editor.setData()` or `editor.data.set()` in real-time collaboration. Re-setting data in real-time collaboration usually means a mistake (incorrect integration or plugin). Using it may overwrite local (not yet synchronized) changes on remote clients. If you tried to set editor initial data, use `initialData` configuration option instead. If you tried to set editor data in a plugin, consider applying the changes through the `Writer` in a `model.change()`block. If you understand effects of using `editor.data.set()` in real-time collaboration and want to suppress this error, set `suppressErrorInCollaboration` flag to `true` in the second parameter of `editor.data.set()` call: `editor.data.set( '<p>Your data</p>', { suppressErrorInCollaboration: true } )`.
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-handleserverresponse">  
####  
`[realtimecollaborationclient-handleserverresponse](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-handleserverresponse)`  
Server response error.
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-document-already-initialized">  
####  
`[realtimecollaborationclient-init-document-already-initialized](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-document-already-initialized)`  
Trying to set initial data to initialized document.
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-non-existent-root">  
####  
`[realtimecollaborationclient-init-non-existent-root](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-non-existent-root)`  
Attempting to init data on a non-existing root.
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-service-internal-error">  
####  
`[realtimecollaborationclient-init-service-internal-error](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-service-internal-error)`  
Internal `CollaborativeEditingService` error.
* <a id="ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-session-connection-error">  
####  
`[realtimecollaborationclient-init-session-connection-error](#ckeditor5/latest/support/error-codes.html--error-realtimecollaborationclient-init-session-connection-error)`  
Connecting to the session resulted in an error.
* <a id="ckeditor5/latest/support/error-codes.html--error-rename-operation-wrong-name">  
####  
`[rename-operation-wrong-name](#ckeditor5/latest/support/error-codes.html--error-rename-operation-wrong-name)`  
Element to change has different name than operation's old name.
* <a id="ckeditor5/latest/support/error-codes.html--error-rename-operation-wrong-position">  
####  
`[rename-operation-wrong-position](#ckeditor5/latest/support/error-codes.html--error-rename-operation-wrong-position)`  
Given position is invalid or node after it is not instance of Element.
* <a id="ckeditor5/latest/support/error-codes.html--error-revision-history-missing-configuration">  
####  
`[revision-history-missing-configuration](#ckeditor5/latest/support/error-codes.html--error-revision-history-missing-configuration)`  
Configuration for revision history plugin is missing.  
Please refer to [documentation](../api/module%5Frevision-history%5Frevisionhistoryconfig-RevisionHistoryConfig.html) to learn how to set up the plugin.
* <a id="ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-attribute-exists">  
####  
`[rootattribute-operation-attribute-exists](#ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-attribute-exists)`  
The attribute with given key already exists for the given node.  
##### Parameters  
`root : [ModelRootElement](../api/module%5Fengine%5Fmodel%5Frootelement-ModelRootElement.html)`  
The root element.  
`key : string`  
The key of the attribute.
* <a id="ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-fromjson-no-root">  
####  
`[rootattribute-operation-fromjson-no-root](#ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-fromjson-no-root)`  
Cannot create RootAttributeOperation for document. Root with the specified name does not exist.  
##### Parameters  
`rootName : string`  
The root name.
* <a id="ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-not-a-root">  
####  
`[rootattribute-operation-not-a-root](#ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-not-a-root)`  
The element to change is not a root element.  
##### Parameters  
`root : [ModelRootElement](../api/module%5Fengine%5Fmodel%5Frootelement-ModelRootElement.html)`  
The root element.  
`key : string`  
The key of the attribute.
* <a id="ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-wrong-old-value">  
####  
`[rootattribute-operation-wrong-old-value](#ckeditor5/latest/support/error-codes.html--error-rootattribute-operation-wrong-old-value)`  
The attribute which should be removed does not exist for the given node.  
##### Parameters  
`root : [ModelRootElement](../api/module%5Fengine%5Fmodel%5Frootelement-ModelRootElement.html)`  
The root element.  
`key : string`  
The key of the attribute.
* <a id="ckeditor5/latest/support/error-codes.html--error-schema-cannot-extend-missing-item">  
####  
`[schema-cannot-extend-missing-item](#ckeditor5/latest/support/error-codes.html--error-schema-cannot-extend-missing-item)`  
Cannot extend an item which was not registered yet.  
This error happens when a plugin tries to extend the schema definition of an item which was not [registered](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-register) yet.  
##### Parameters  
`itemName : any`  
The name of the model element which is being extended.
* <a id="ckeditor5/latest/support/error-codes.html--error-schema-cannot-register-item-twice">  
####  
`[schema-cannot-register-item-twice](#ckeditor5/latest/support/error-codes.html--error-schema-cannot-register-item-twice)`  
A single item cannot be registered twice in the schema.  
This situation may happen when:

  * Two or more plugins called [register()](../api/module%5Fengine%5Fmodel%5Fschema-ModelSchema.html#function-register) with the same name. This will usually mean that there is a collision between plugins which try to use the same element in the model. Unfortunately, the only way to solve this is by modifying one of these plugins to use a unique model element name.
  * A single plugin was loaded twice. This happens when it is installed by npm/yarn in two versions and usually means one or more of the following issues:  
    * a version mismatch (two of your dependencies require two different versions of this plugin),
    * incorrect imports (this plugin is somehow imported twice in a way which confuses webpack),
    * mess in `node_modules/` (`rm -rf node_modules/` may help).

**Note:** Check the logged `itemName` to better understand which plugin was duplicated/conflicting.  
##### Parameters  
`itemName : any`  
The name of the model element that is being registered twice.
* <a id="ckeditor5/latest/support/error-codes.html--error-schema-check-merge-no-element-after">  
####  
`[schema-check-merge-no-element-after](#ckeditor5/latest/support/error-codes.html--error-schema-check-merge-no-element-after)`  
The node after the merge position must be an element.
* <a id="ckeditor5/latest/support/error-codes.html--error-schema-check-merge-no-element-before">  
####  
`[schema-check-merge-no-element-before](#ckeditor5/latest/support/error-codes.html--error-schema-check-merge-no-element-before)`  
The node before the merge position must be an element.
* <a id="ckeditor5/latest/support/error-codes.html--error-sessions-register-already-registered">  
####  
`[sessions-register-already-registered](#ckeditor5/latest/support/error-codes.html--error-sessions-register-already-registered)`  
Sessions of given channelId already registered.
* <a id="ckeditor5/latest/support/error-codes.html--error-sessions-unregister-not-exist">  
####  
`[sessions-unregister-not-exist](#ckeditor5/latest/support/error-codes.html--error-sessions-unregister-not-exist)`  
Cannot unregister not registered sessions.
* <a id="ckeditor5/latest/support/error-codes.html--error-sidebar-attachtocontainer-missing-container">  
####  
`[sidebar-attachtocontainer-missing-container](#ckeditor5/latest/support/error-codes.html--error-sidebar-attachtocontainer-missing-container)`  
Missing container element.
* <a id="ckeditor5/latest/support/error-codes.html--error-sidebar-setcontainer-invalid-element">  
####  
`[sidebar-setcontainer-invalid-element](#ckeditor5/latest/support/error-codes.html--error-sidebar-setcontainer-invalid-element)`  
Container element is not a HTMLElement.
* <a id="ckeditor5/latest/support/error-codes.html--error-simple-upload-adapter-missing-uploadurl">  
####  
`[simple-upload-adapter-missing-uploadurl](#ckeditor5/latest/support/error-codes.html--error-simple-upload-adapter-missing-uploadurl)`  
The [config.simpleUpload.uploadUrl](../api/module%5Fupload%5Fuploadconfig-SimpleUploadConfig.html#member-uploadUrl)configuration required by the [SimpleUploadAdapter](../api/module%5Fupload%5Fadapters%5Fsimpleuploadadapter-SimpleUploadAdapter.html)is missing. Make sure the correct URL is specified for the image upload to work properly.
* <a id="ckeditor5/latest/support/error-codes.html--error-slash-command-execute-missing">  
####  
`[slash-command-execute-missing](#ckeditor5/latest/support/error-codes.html--error-slash-command-execute-missing)`  
Either [execute](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-execute) or [commandName](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html#member-commandName)has to be specified in [SlashCommandDefinition](../api/module%5Fslash-command%5Fslashcommandconfig-SlashCommandDefinition.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-slash-command-invalid-license-key">  
####  
`[slash-command-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-slash-command-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-slash-command-trial-license-key-reached-limit-changes">  
####  
`[slash-command-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-slash-command-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-source-editing-enhanced-incompatible-with-real-time-collaboration">  
####  
`[source-editing-enhanced-incompatible-with-real-time-collaboration](#ckeditor5/latest/support/error-codes.html--error-source-editing-enhanced-incompatible-with-real-time-collaboration)`  
Source editing enhanced feature is not fully compatible with real-time collaboration, and using it may lead to data loss. Please read [source editing enhanced feature guide](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html--limitations-and-incompatibilities)to learn more.  
If you understand the possible risk of data loss, you can enable the source editing enhanced by setting the [allowCollaborationFeatures](../api/module%5Fsource-editing-enhanced%5Fsourceeditingenhancedconfig-SourceEditingEnhancedConfig.html#member-allowCollaborationFeatures)configuration flag to `true`.
* <a id="ckeditor5/latest/support/error-codes.html--error-source-editing-incompatible-with-real-time-collaboration">  
####  
`[source-editing-incompatible-with-real-time-collaboration](#ckeditor5/latest/support/error-codes.html--error-source-editing-incompatible-with-real-time-collaboration)`  
Source editing feature is not fully compatible with real-time collaboration, and using it may lead to data loss. Please read [source editing feature guide](#ckeditor5/latest/features/source-editing/source-editing.html--limitations-and-incompatibilities) to learn more.  
If you understand the possible risk of data loss, you can enable the source editing by setting the [allowCollaborationFeatures](../api/module%5Fsource-editing%5Fsourceeditingconfig-SourceEditingConfig.html#member-allowCollaborationFeatures)configuration flag to `true`.
* <a id="ckeditor5/latest/support/error-codes.html--error-special-character-invalid-group-name">  
####  
`[special-character-invalid-group-name](#ckeditor5/latest/support/error-codes.html--error-special-character-invalid-group-name)`  
The name "All" for a special category group cannot be used because it is a special category that displays all available special characters.
* <a id="ckeditor5/latest/support/error-codes.html--error-special-character-invalid-order-group-name">  
####  
`[special-character-invalid-order-group-name](#ckeditor5/latest/support/error-codes.html--error-special-character-invalid-order-group-name)`  
One of the special character groups in the "specialCharacters.order" configuration doesn't exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-split-operation-graveyard-position-invalid">  
####  
`[split-operation-graveyard-position-invalid](#ckeditor5/latest/support/error-codes.html--error-split-operation-graveyard-position-invalid)`  
Graveyard position invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-split-operation-how-many-invalid">  
####  
`[split-operation-how-many-invalid](#ckeditor5/latest/support/error-codes.html--error-split-operation-how-many-invalid)`  
Split operation specifies wrong number of nodes to move.
* <a id="ckeditor5/latest/support/error-codes.html--error-split-operation-position-invalid">  
####  
`[split-operation-position-invalid](#ckeditor5/latest/support/error-codes.html--error-split-operation-position-invalid)`  
Split position is invalid.
* <a id="ckeditor5/latest/support/error-codes.html--error-split-operation-split-in-root">  
####  
`[split-operation-split-in-root](#ckeditor5/latest/support/error-codes.html--error-split-operation-split-in-root)`  
Cannot split root element.
* <a id="ckeditor5/latest/support/error-codes.html--error-style-command-executed-with-incorrect-style-name">  
####  
`[style-command-executed-with-incorrect-style-name](#ckeditor5/latest/support/error-codes.html--error-style-command-executed-with-incorrect-style-name)`  
Style command can be executed only with a correct style name.  
This warning may be caused by:

  * passing a name that is not specified in the [configuration](../api/module%5Fstyle%5Fstyleconfig-StyleConfig.html#member-definitions)(e.g. a CSS class name),
  * when trying to apply a style that is not allowed on a given element.
* <a id="ckeditor5/latest/support/error-codes.html--error-table-of-contents-invalid-license-key">  
####  
`[table-of-contents-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-table-of-contents-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-table-of-contents-trial-license-key-reached-limit-changes">  
####  
`[table-of-contents-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-table-of-contents-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-tableslot-getter-removed">  
####  
`[tableslot-getter-removed](#ckeditor5/latest/support/error-codes.html--error-tableslot-getter-removed)`  
This `TableSlot`'s getter (property) was removed in CKEditor 5 v20.0.0.  
Check out the new `TableWalker`'s API in the documentation.
* <a id="ckeditor5/latest/support/error-codes.html--error-tableutils-insertrows-insert-out-of-range">  
####  
`[tableutils-insertrows-insert-out-of-range](#ckeditor5/latest/support/error-codes.html--error-tableutils-insertrows-insert-out-of-range)`  
The `options.at` points at a row position that does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-tableutils-removerows-row-index-out-of-range">  
####  
`[tableutils-removerows-row-index-out-of-range](#ckeditor5/latest/support/error-codes.html--error-tableutils-removerows-row-index-out-of-range)`  
The `options.at` param must point at existing row and `options.rows` must not exceed the rows in the table.
* <a id="ckeditor5/latest/support/error-codes.html--error-template-extend-render">  
####  
`[template-extend-render](#ckeditor5/latest/support/error-codes.html--error-template-extend-render)`  
Extending a template after rendering may not work as expected. To make sure the [extending](../api/module%5Fui%5Ftemplate-Template.html#static-function-extend) works for an element, make sure it happens before [render](../api/module%5Fui%5Ftemplate-Template.html#function-render) is called.
* <a id="ckeditor5/latest/support/error-codes.html--error-template-invalid-license-key">  
####  
`[template-invalid-license-key](#ckeditor5/latest/support/error-codes.html--error-template-invalid-license-key)`  
Invalid license key. Please contact our customer support at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-template-trial-license-key-reached-limit-changes">  
####  
`[template-trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-template-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-token-cannot-download-new-token">  
####  
`[token-cannot-download-new-token](#ckeditor5/latest/support/error-codes.html--error-token-cannot-download-new-token)`  
Cannot download new token from the provided url.
* <a id="ckeditor5/latest/support/error-codes.html--error-token-missing-token-url">  
####  
`[token-missing-token-url](#ckeditor5/latest/support/error-codes.html--error-token-missing-token-url)`  
A `tokenUrl` must be provided as the first constructor argument.
* <a id="ckeditor5/latest/support/error-codes.html--error-token-not-in-jwt-format">  
####  
`[token-not-in-jwt-format](#ckeditor5/latest/support/error-codes.html--error-token-not-in-jwt-format)`  
The provided token must follow the [JSON Web Tokens](https://jwt.io/introduction/) format.
* <a id="ckeditor5/latest/support/error-codes.html--error-token-refresh-failed">  
####  
`[token-refresh-failed](#ckeditor5/latest/support/error-codes.html--error-token-refresh-failed)`  
You will see this warning when the CKEditor [token](../api/module%5Fcloud-services%5Ftoken%5Ftoken-Token.html) could not be refreshed. This may be a result of a network error, a token endpoint (server) error, or an invalid [token URL configuration](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl).  
If this warning repeats, please make sure that the configuration is correct and that the token endpoint is up and running. [Learn more](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl)about token configuration.

**Note:** If the token's [auto refresh option](../api/module%5Fcloud-services%5Ftoken%5Ftoken-CloudServicesTokenOptions.html)is enabled, attempts to refresh will be made until success or token's [destruction](../api/module%5Fcloud-services%5Ftoken%5Ftoken-Token.html#function-destroy).  
##### Parameters  
`autoRefresh : boolean`  
Whether the token will keep auto refreshing.
* <a id="ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable">  
####  
`[toolbarview-item-unavailable](#ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable)`  
There was a problem processing the configuration of the toolbar. The item with the given name does not exist so it was omitted when rendering the toolbar.  
This warning usually shows up when the [Plugin](../api/module%5Fcore%5Fplugin-Plugin.html) which is supposed to provide a toolbar item has not been loaded or there is a typo in the [toolbar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).  
Make sure the plugin responsible for this toolbar item is loaded and the toolbar configuration is correct, e.g. [Bold](../api/module%5Fbasic-styles%5Fbold-Bold.html) is loaded for the `'bold'` toolbar item.  
You can use the following snippet to retrieve all available toolbar items:  
```  
Array.from( editor.ui.componentFactory.names() );  
```  
##### Parameters  
`item : string`  
The name of the component or nested toolbar definition.
* <a id="ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable  
%2A">  
####  
`[toolbarview-item-unavailable *](#ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable%2A)`  
Logs a warning to the console with a properly formatted message and adds a link to the documentation. Use whenever you want to log a warning to the console.  
```  
/**
 * There was a problem processing the configuration of the toolbar. The item with the given
 * name does not exist, so it was omitted when rendering the toolbar.
 *
 *  
```  
##### Parameters  
`name : String`  
The name of the component.  
`errorName : any`  
The error name to be logged.  
`data : any`  
Additional data to be logged.
* <a id="ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable  
%2A">  
####  
`[toolbarview-item-unavailable *](#ckeditor5/latest/support/error-codes.html--error-toolbarview-item-unavailable%2A)`  
Logs an error to the console with a properly formatted message and adds a link to the documentation. Use whenever you want to log an error to the console.  
```  
/**
 * There was a problem processing the configuration of the toolbar. The item with the given
 * name does not exist, so it was omitted when rendering the toolbar.
 *
 *  
```  
##### Parameters  
`name : String`  
The name of the component.  
`errorName : any`  
The error name to be logged.  
`data : any`  
Additional data to be logged.
* <a id="ckeditor5/latest/support/error-codes.html--error-toolbarview-line-break-ignored-when-grouping-items">  
####  
`[toolbarview-line-break-ignored-when-grouping-items](#ckeditor5/latest/support/error-codes.html--error-toolbarview-line-break-ignored-when-grouping-items)`  
The toolbar multiline breaks (`-` items) only work when the automatic button grouping is disabled in the toolbar configuration. To do this, set the `shouldNotGroupWhenFull` option to `true` in the editor configuration:  
```  
const config = {  
	toolbar: {  
		items: [ ... ],  
		shouldNotGroupWhenFull: true  
	}  
}  
```  
Learn more about [toolbar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).
* <a id="ckeditor5/latest/support/error-codes.html--error-toolbarview-nested-toolbar-dropdown-missing-label">  
####  
`[toolbarview-nested-toolbar-dropdown-missing-label](#ckeditor5/latest/support/error-codes.html--error-toolbarview-nested-toolbar-dropdown-missing-label)`  
A dropdown definition in the toolbar configuration is missing a text label.  
Without a label, the dropdown becomes inaccessible to users relying on assistive technologies. Make sure the `label` property is set in your drop-down configuration:  
```  
 {  
 	label: 'A human-readable label',  
	icon: '...',  
	items: [ ... ]  
 },  
```  
Learn more about [toolbar configuration](../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-accept-suggestion-not-found">  
####  
`[track-changes-accept-suggestion-not-found](#ckeditor5/latest/support/error-codes.html--error-track-changes-accept-suggestion-not-found)`  
Suggestion to accept does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-adapter-already-set">  
####  
`[track-changes-adapter-already-set](#ckeditor5/latest/support/error-codes.html--error-track-changes-adapter-already-set)`  
Cannot set an adapter more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-adapter-missing-getsuggestion">  
####  
`[track-changes-adapter-missing-getsuggestion](#ckeditor5/latest/support/error-codes.html--error-track-changes-adapter-missing-getsuggestion)`  
Adapter not set or is missing `getSuggestion()` method.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-command-not-found">  
####  
`[track-changes-command-not-found](#ckeditor5/latest/support/error-codes.html--error-track-changes-command-not-found)`  
Trying to enable command that does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-data-invalid-editor-creator">  
####  
`[track-changes-data-invalid-editor-creator](#ckeditor5/latest/support/error-codes.html--error-track-changes-data-invalid-editor-creator)`  
Editor creator has to be a function.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-discard-suggestion-not-found">  
####  
`[track-changes-discard-suggestion-not-found](#ckeditor5/latest/support/error-codes.html--error-track-changes-discard-suggestion-not-found)`  
Suggestion to discard does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-enable-command-twice">  
####  
`[track-changes-enable-command-twice](#ckeditor5/latest/support/error-codes.html--error-track-changes-enable-command-twice)`  
Trying to enable the same command twice.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-suggestion-data-mismatch">  
####  
`[track-changes-suggestion-data-mismatch](#ckeditor5/latest/support/error-codes.html--error-track-changes-suggestion-data-mismatch)`  
Suggestion marker data does not match loaded suggestion data.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-suggestion-not-found">  
####  
`[track-changes-suggestion-not-found](#ckeditor5/latest/support/error-codes.html--error-track-changes-suggestion-not-found)`  
Suggestion with given id not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-track-changes-user-not-found">  
####  
`[track-changes-user-not-found](#ckeditor5/latest/support/error-codes.html--error-track-changes-user-not-found)`  
User with the ID specified in suggestion `authorId` property not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-translation-service-quantity-not-a-number">  
####  
`[translation-service-quantity-not-a-number](#ckeditor5/latest/support/error-codes.html--error-translation-service-quantity-not-a-number)`  
An incorrect value was passed to the translation function. This was probably caused by an incorrect message interpolation of a plural form. Note that for messages supporting plural forms the second argument of the `t()` function should always be a number or an array with a number as the first element.
* <a id="ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-changes">  
####  
`[trial-license-key-reached-limit-changes](#ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-changes)`  
You have exhausted the trial usage limit (reason: reached document changes limit). Restart the editor.  
Please contact our customer support to get full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-revisions">  
####  
`[trial-license-key-reached-limit-revisions](#ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-revisions)`  
You have exhausted the trial usage limit (reason: reached revisions number limit).  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-time">  
####  
`[trial-license-key-reached-limit-time](#ckeditor5/latest/support/error-codes.html--error-trial-license-key-reached-limit-time)`  
You have exhausted the trial usage limit (reason: reached time limit). Restart the editor.  
Please contact our customer support to get a full access at https://ckeditor.com/contact/.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-dropdown-focus-child-on-open-child-missing-focus">  
####  
`[ui-dropdown-focus-child-on-open-child-missing-focus](#ckeditor5/latest/support/error-codes.html--error-ui-dropdown-focus-child-on-open-child-missing-focus)`  
The child view of a [dropdown](../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html) is missing the `focus()` method and could not be focused when the dropdown got [open](../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-isOpen).  
Making the content of a dropdown focusable in this case greatly improves the accessibility. Please make the view instance implements the [focusable interface](../api/module%5Fui%5Fdropdown%5Fdropdownpanelfocusable-DropdownPanelFocusable.html) for the best user experience.  
##### Parameters  
`view : [View](../api/module%5Fui%5Fview-View.html)`  
Child to focus.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-dropdown-panel-focus-child-missing-focus">  
####  
`[ui-dropdown-panel-focus-child-missing-focus](#ckeditor5/latest/support/error-codes.html--error-ui-dropdown-panel-focus-child-missing-focus)`  
The child view of a dropdown could not be focused because it is missing the `focus()` method.  
This warning appears when a dropdown [gets open](../api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html#member-isOpen) and it attempts to focus the [first child](../api/module%5Fui%5Fdropdown%5Fdropdownpanelview-DropdownPanelView.html#member-children) of its panel but the child does not implement the [focusable interface](../api/module%5Fui%5Fdropdown%5Fdropdownpanelfocusable-DropdownPanelFocusable.html).  
Focusing the content of a dropdown on open greatly improves the accessibility. Please make sure the view instance provides the `focus()` method for the best user experience.  
##### Parameters  
`childView : [View](../api/module%5Fui%5Fview-View.html)`  
Child view.  
`dropdownPanel : [DropdownPanelView](../api/module%5Fui%5Fdropdown%5Fdropdownpanelview-DropdownPanelView.html)`  
A parent of a child.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-iconview-invalid-svg">  
####  
`[ui-iconview-invalid-svg](#ckeditor5/latest/support/error-codes.html--error-ui-iconview-invalid-svg)`  
The provided icon content is not a valid SVG.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-tabsview-tab-not-found">  
####  
`[ui-tabsview-tab-not-found](#ckeditor5/latest/support/error-codes.html--error-ui-tabsview-tab-not-found)`  
The tab with the given ID was not found.  
##### Parameters  
`tabs : [AITabsView](../api/module%5Fai%5Faitabs%5Ftabs%5Faitabsview-AITabsView.html)`  
The tabs view instance.  
`tabId : string`  
The ID of the tab that was not found.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-template-extend-children-mismatch">  
####  
`[ui-template-extend-children-mismatch](#ckeditor5/latest/support/error-codes.html--error-ui-template-extend-children-mismatch)`  
The number of children in extended definition does not match.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-template-revert-not-applied">  
####  
`[ui-template-revert-not-applied](#ckeditor5/latest/support/error-codes.html--error-ui-template-revert-not-applied)`  
Attempting to revert a template which has not been applied yet.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-template-wrong-syntax">  
####  
`[ui-template-wrong-syntax](#ckeditor5/latest/support/error-codes.html--error-ui-template-wrong-syntax)`  
Node definition cannot have the "tag" and "text" properties at the same time. Node definition must have either "tag" or "text" when rendering a new Node.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-textarea-view-min-rows-greater-than-max-rows">  
####  
`[ui-textarea-view-min-rows-greater-than-max-rows](#ckeditor5/latest/support/error-codes.html--error-ui-textarea-view-min-rows-greater-than-max-rows)`  
The minimum number of rows is greater than the maximum number of rows.  
##### Parameters  
`textareaView : [TextareaView](../api/module%5Fui%5Ftextarea%5Ftextareaview-TextareaView.html)`  
The misconfigured textarea view instance.  
`minRows : number`  
The value of `minRows` property.  
`maxRows : number`  
The value of `maxRows` property.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-view-render-already-rendered">  
####  
`[ui-view-render-already-rendered](#ckeditor5/latest/support/error-codes.html--error-ui-view-render-already-rendered)`  
This View has already been rendered.
* <a id="ckeditor5/latest/support/error-codes.html--error-ui-viewcollection-delegate-wrong-events">  
####  
`[ui-viewcollection-delegate-wrong-events](#ckeditor5/latest/support/error-codes.html--error-ui-viewcollection-delegate-wrong-events)`  
All event names must be strings.
* <a id="ckeditor5/latest/support/error-codes.html--error-unexpected-error">  
####  
`[unexpected-error](#ckeditor5/latest/support/error-codes.html--error-unexpected-error)`  
An unexpected error occurred inside the CKEditor 5 codebase. This error will look like the original one to make the debugging easier.  
This error is only useful when the editor is initialized using the [Watchdog](../api/module%5Fwatchdog%5Fwatchdog-Watchdog.html) feature. In case of such error (or any [CKEditorError](../api/module%5Futils%5Fckeditorerror-CKEditorError.html) error) the watchdog should restart the editor.
* <a id="ckeditor5/latest/support/error-codes.html--error-update-bookmark-command-executed-with-invalid-name">  
####  
`[update-bookmark-command-executed-with-invalid-name](#ckeditor5/latest/support/error-codes.html--error-update-bookmark-command-executed-with-invalid-name)`  
Update bookmark command can be executed only with a valid name.  
A valid bookmark name must be a non-empty string and must not contain any spaces.
* <a id="ckeditor5/latest/support/error-codes.html--error-uploadgateway-missing-api-address">  
####  
`[uploadgateway-missing-api-address](#ckeditor5/latest/support/error-codes.html--error-uploadgateway-missing-api-address)`  
Api address must be provided.
* <a id="ckeditor5/latest/support/error-codes.html--error-uploadgateway-missing-token">  
####  
`[uploadgateway-missing-token](#ckeditor5/latest/support/error-codes.html--error-uploadgateway-missing-token)`  
Token must be provided.
* <a id="ckeditor5/latest/support/error-codes.html--error-users-add-duplicated-id">  
####  
`[users-add-duplicated-id](#ckeditor5/latest/support/error-codes.html--error-users-add-duplicated-id)`  
User with a given id is already added.
* <a id="ckeditor5/latest/support/error-codes.html--error-users-add-invalid-id">  
####  
`[users-add-invalid-id](#ckeditor5/latest/support/error-codes.html--error-users-add-invalid-id)`  
The id must be a string.
* <a id="ckeditor5/latest/support/error-codes.html--error-users-me-already-defined">  
####  
`[users-me-already-defined](#ckeditor5/latest/support/error-codes.html--error-users-me-already-defined)`  
Cannot add a local user more than once.
* <a id="ckeditor5/latest/support/error-codes.html--error-users-me-missing-user">  
####  
`[users-me-missing-user](#ckeditor5/latest/support/error-codes.html--error-users-me-missing-user)`  
Cannot specify a non-existing user as the local user.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-conversion-dispatcher-incorrect-result">  
####  
`[view-conversion-dispatcher-incorrect-result](#ckeditor5/latest/support/error-codes.html--error-view-conversion-dispatcher-incorrect-result)`  
Incorrect conversion result was dropped.  
[Model range](../api/module%5Fengine%5Fmodel%5Frange-ModelRange.html) should be a conversion result.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-createpositionat-offset-required">  
####  
`[view-createpositionat-offset-required](#ckeditor5/latest/support/error-codes.html--error-view-createpositionat-offset-required)`  
[View#createPositionAt()](../api/module%5Fengine%5Fview%5Fview-EditingView.html#function-createPositionAt)requires the offset to be specified when the first parameter is a view item.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-emptyelement-cannot-add">  
####  
`[view-emptyelement-cannot-add](#ckeditor5/latest/support/error-codes.html--error-view-emptyelement-cannot-add)`  
Cannot add children to [ViewEmptyElement](../api/module%5Fengine%5Fview%5Femptyelement-ViewEmptyElement.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-view-node-not-found-in-parent">  
####  
`[view-node-not-found-in-parent](#ckeditor5/latest/support/error-codes.html--error-view-node-not-found-in-parent)`  
The node's parent does not contain this node. It means that the document tree is corrupted.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-position-after-root">  
####  
`[view-position-after-root](#ckeditor5/latest/support/error-codes.html--error-view-position-after-root)`  
You cannot make a position after a root.  
##### Parameters  
`root : [ViewNode](../api/module%5Fengine%5Fview%5Fnode-ViewNode.html)`  
A root item.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-position-before-root">  
####  
`[view-position-before-root](#ckeditor5/latest/support/error-codes.html--error-view-position-before-root)`  
You cannot make a position before a root.  
##### Parameters  
`root : [ViewNode](../api/module%5Fengine%5Fview%5Fnode-ViewNode.html)`  
A root item.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-rawelement-cannot-add">  
####  
`[view-rawelement-cannot-add](#ckeditor5/latest/support/error-codes.html--error-view-rawelement-cannot-add)`  
Cannot add children to a [ViewRawElement](../api/module%5Fengine%5Fview%5Frawelement-ViewRawElement.html) instance.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-renderer-filler-was-lost">  
####  
`[view-renderer-filler-was-lost](#ckeditor5/latest/support/error-codes.html--error-view-renderer-filler-was-lost)`  
The inline filler node was lost. Most likely, something overwrote the filler text node in the DOM.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-renderer-unknown-type">  
####  
`[view-renderer-unknown-type](#ckeditor5/latest/support/error-codes.html--error-view-renderer-unknown-type)`  
Unknown type passed to Renderer.markToSync.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-selection-add-range-not-range">  
####  
`[view-selection-add-range-not-range](#ckeditor5/latest/support/error-codes.html--error-view-selection-add-range-not-range)`  
Selection range set to an object that is not an instance of [ViewRange](../api/module%5Fengine%5Fview%5Frange-ViewRange.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-view-selection-range-intersects">  
####  
`[view-selection-range-intersects](#ckeditor5/latest/support/error-codes.html--error-view-selection-range-intersects)`  
Trying to add a range that intersects with another range from selection.  
##### Parameters  
`addedRange : [ViewRange](../api/module%5Fengine%5Fview%5Frange-ViewRange.html)`  
Range that was added to the selection.  
`intersectingRange : [ViewRange](../api/module%5Fengine%5Fview%5Frange-ViewRange.html)`  
Range from selection that intersects with `addedRange`.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-selection-setfocus-no-ranges">  
####  
`[view-selection-setfocus-no-ranges](#ckeditor5/latest/support/error-codes.html--error-view-selection-setfocus-no-ranges)`  
Cannot set selection focus if there are no ranges in selection.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-selection-setto-not-selectable">  
####  
`[view-selection-setto-not-selectable](#ckeditor5/latest/support/error-codes.html--error-view-selection-setto-not-selectable)`  
Cannot set selection to given place.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-selection-setto-required-second-parameter">  
####  
`[view-selection-setto-required-second-parameter](#ckeditor5/latest/support/error-codes.html--error-view-selection-setto-required-second-parameter)`  
selection.setTo requires the second parameter when the first parameter is a node.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-textproxy-wrong-length">  
####  
`[view-textproxy-wrong-length](#ckeditor5/latest/support/error-codes.html--error-view-textproxy-wrong-length)`  
Given length value is incorrect.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-textproxy-wrong-offsetintext">  
####  
`[view-textproxy-wrong-offsetintext](#ckeditor5/latest/support/error-codes.html--error-view-textproxy-wrong-offsetintext)`  
Given offsetInText value is incorrect.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-tree-walker-no-start-position">  
####  
`[view-tree-walker-no-start-position](#ckeditor5/latest/support/error-codes.html--error-view-tree-walker-no-start-position)`  
Neither boundaries nor starting position have been defined.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-tree-walker-unknown-direction">  
####  
`[view-tree-walker-unknown-direction](#ckeditor5/latest/support/error-codes.html--error-view-tree-walker-unknown-direction)`  
Only `backward` and `forward` direction allowed.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-uielement-cannot-add">  
####  
`[view-uielement-cannot-add](#ckeditor5/latest/support/error-codes.html--error-view-uielement-cannot-add)`  
Cannot add children to [ViewUIElement](../api/module%5Fengine%5Fview%5Fuielement-ViewUIElement.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-break-non-container-element">  
####  
`[view-writer-break-non-container-element](#ckeditor5/latest/support/error-codes.html--error-view-writer-break-non-container-element)`  
Trying to break an element which is not a container element.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-break-root">  
####  
`[view-writer-break-root](#ckeditor5/latest/support/error-codes.html--error-view-writer-break-root)`  
Trying to break root element.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-empty-element">  
####  
`[view-writer-cannot-break-empty-element](#ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-empty-element)`  
Cannot break an `EmptyElement` instance.  
This error is thrown if [ViewDowncastWriter#breakAttributes()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-breakAttributes)was executed in an incorrect position.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-raw-element">  
####  
`[view-writer-cannot-break-raw-element](#ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-raw-element)`  
Cannot break a `RawElement` instance.  
This error is thrown if [ViewDowncastWriter#breakAttributes()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-breakAttributes)was executed in an incorrect position.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-ui-element">  
####  
`[view-writer-cannot-break-ui-element](#ckeditor5/latest/support/error-codes.html--error-view-writer-cannot-break-ui-element)`  
Cannot break a `UIElement` instance.  
This error is thrown if [ViewDowncastWriter#breakAttributes()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-breakAttributes)was executed in an incorrect position.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-insert-invalid-node-type">  
####  
`[view-writer-insert-invalid-node-type](#ckeditor5/latest/support/error-codes.html--error-view-writer-insert-invalid-node-type)`  
One of the nodes to be inserted is of an invalid type.  
Nodes to be inserted with [ViewDowncastWriter#insert()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-insert)should be of the following types:

  * [ViewAttributeElement](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html),
  * [ViewContainerElement](../api/module%5Fengine%5Fview%5Fcontainerelement-ViewContainerElement.html),
  * [ViewEmptyElement](../api/module%5Fengine%5Fview%5Femptyelement-ViewEmptyElement.html),
  * [UIElement](../api/module%5Fengine%5Fview%5Fuielement-ViewUIElement.html),
  * [RawElement](../api/module%5Fengine%5Fview%5Frawelement-ViewRawElement.html),
  * [Text](../api/module%5Fengine%5Fview%5Ftext-ViewText.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-create-slot-context">  
####  
`[view-writer-invalid-create-slot-context](#ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-create-slot-context)`  
The `createSlot()` method is only allowed inside the `elementToStructure` downcast helper callback.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-position-container">  
####  
`[view-writer-invalid-position-container](#ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-position-container)`  
Position's parent container cannot be found.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-range-container">  
####  
`[view-writer-invalid-range-container](#ckeditor5/latest/support/error-codes.html--error-view-writer-invalid-range-container)`  
The container of the given range is invalid.  
This may happen if [range start](../api/module%5Fengine%5Fview%5Frange-ViewRange.html#member-start) and [range end](../api/module%5Fengine%5Fview%5Frange-ViewRange.html#member-end) positions are not placed inside the same container element or a parent container for these positions cannot be found.  
Methods like [ViewDowncastWriter#remove()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-wrap), [ViewDowncastWriter#clean()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-wrap), [ViewDowncastWriter#wrap()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-wrap), [ViewDowncastWriter#unwrap()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-wrap) need to be called on a range that has its start and end positions located in the same container element. Both positions can be nested within other elements (e.g. an attribute element) but the closest container ancestor must be the same.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-merge-containers-invalid-position">  
####  
`[view-writer-merge-containers-invalid-position](#ckeditor5/latest/support/error-codes.html--error-view-writer-merge-containers-invalid-position)`  
Element before and after given position cannot be merged.
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-unwrap-invalid-attribute">  
####  
`[view-writer-unwrap-invalid-attribute](#ckeditor5/latest/support/error-codes.html--error-view-writer-unwrap-invalid-attribute)`  
The `attribute` passed to [ViewDowncastWriter#unwrap()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-unwrap)must be an instance of [AttributeElement](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-view-writer-wrap-invalid-attribute">  
####  
`[view-writer-wrap-invalid-attribute](#ckeditor5/latest/support/error-codes.html--error-view-writer-wrap-invalid-attribute)`  
The `attribute` passed to [ViewDowncastWriter#wrap()](../api/module%5Fengine%5Fview%5Fdowncastwriter-ViewDowncastWriter.html#function-wrap)must be an instance of [AttributeElement](../api/module%5Fengine%5Fview%5Fattributeelement-ViewAttributeElement.html).
* <a id="ckeditor5/latest/support/error-codes.html--error-viewconsumable-invalid-attribute">  
####  
`[viewconsumable-invalid-attribute](#ckeditor5/latest/support/error-codes.html--error-viewconsumable-invalid-attribute)`  
Class and style attributes should be handled separately in [ViewConsumable#add()](../api/module%5Fengine%5Fconversion%5Fviewconsumable-ViewConsumable.html#function-add).  
What you have done is trying to use:  
```  
consumables.add( { attributes: [ 'class', 'style' ] } );  
```  
While each class and style should be registered separately:  
```  
consumables.add( { classes: 'some-class', styles: 'font-weight' } );  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-websocketgateway-invalid-plugin-interface">  
####  
`[websocketgateway-invalid-plugin-interface](#ckeditor5/latest/support/error-codes.html--error-websocketgateway-invalid-plugin-interface)`  
Cannot add a plugin that does not implement the `reconnect()` method to the `WebSocketGateway` reconnection stack.
* <a id="ckeditor5/latest/support/error-codes.html--error-websocketgateway-missing-token">  
####  
`[websocketgateway-missing-token](#ckeditor5/latest/support/error-codes.html--error-websocketgateway-missing-token)`  
The authentication [tokenUrl](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) \* `config.cloudServices.tokenUrl`} configuration is required for creating a websocket connection.
* <a id="ckeditor5/latest/support/error-codes.html--error-websocketgateway-missing-websocket-url">  
####  
`[websocketgateway-missing-websocket-url](#ckeditor5/latest/support/error-codes.html--error-websocketgateway-missing-websocket-url)`  
The [config.cloudServices.webSocketUrl](../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-webSocketUrl)configuration is required for creating a websocket connection in the real-time collaboration.  
```  
ClassicEditor.create( {  
	cloudServices: {  
		webSocketUrl: "YOUR_WEBSOCKET_URL"  
		// ...  
	}  
	// ...  
} );  
```
* <a id="ckeditor5/latest/support/error-codes.html--error-websocketgateway-plugin-already-registered">  
####  
`[websocketgateway-plugin-already-registered](#ckeditor5/latest/support/error-codes.html--error-websocketgateway-plugin-already-registered)`  
A plugin was added twice to the `WebSocketGateway` reconnection stack.
* <a id="ckeditor5/latest/support/error-codes.html--error-widesidebar-attach-already-attached">  
####  
`[widesidebar-attach-already-attached](#ckeditor5/latest/support/error-codes.html--error-widesidebar-attach-already-attached)`  
Cannot attach wide sidebar twice.
* <a id="ckeditor5/latest/support/error-codes.html--error-widesidebar-detach-not-attached">  
####  
`[widesidebar-detach-not-attached](#ckeditor5/latest/support/error-codes.html--error-widesidebar-detach-not-attached)`  
Cannot detach not attached sidebar.
* <a id="ckeditor5/latest/support/error-codes.html--error-widget-to-widget-wrong-element-type">  
####  
`[widget-to-widget-wrong-element-type](#ckeditor5/latest/support/error-codes.html--error-widget-to-widget-wrong-element-type)`  
The element passed to `toWidget()` must be a [ViewContainerElement](../api/module%5Fengine%5Fview%5Fcontainerelement-ViewContainerElement.html)instance.  
##### Parameters  
`element : any`  
The view element passed to `toWidget()`.
* <a id="ckeditor5/latest/support/error-codes.html--error-widget-toolbar-duplicated">  
####  
`[widget-toolbar-duplicated](#ckeditor5/latest/support/error-codes.html--error-widget-toolbar-duplicated)`  
Toolbar with the given id was already added.  
##### Parameters  
`toolbarId : string`  
Toolbar id.
* <a id="ckeditor5/latest/support/error-codes.html--error-widget-toolbar-no-items">  
####  
`[widget-toolbar-no-items](#ckeditor5/latest/support/error-codes.html--error-widget-toolbar-no-items)`  
When [registering](../api/module%5Fwidget%5Fwidgettoolbarrepository-WidgetToolbarRepository.html#function-register) a new widget toolbar, you need to provide a non-empty array with the items that will be inserted into the toolbar.  
If you see this error when integrating the editor, you likely forgot to configure one of the widget toolbars.  
See for instance:

  * [config.table.contentToolbar](../api/module%5Ftable%5Ftableconfig-TableConfig.html#member-contentToolbar)
  * [config.image.toolbar](../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-toolbar)  
##### Parameters  
`toolbarId : string`  
The id of the toolbar that has not been configured correctly.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-addmarker-marker-exists">  
####  
`[writer-addmarker-marker-exists](#ckeditor5/latest/support/error-codes.html--error-writer-addmarker-marker-exists)`  
Marker with provided name already exists.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-addmarker-no-range">  
####  
`[writer-addmarker-no-range](#ckeditor5/latest/support/error-codes.html--error-writer-addmarker-no-range)`  
Range parameter is required when adding a new marker.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-addmarker-no-usingoperation">  
####  
`[writer-addmarker-no-usingoperation](#ckeditor5/latest/support/error-codes.html--error-writer-addmarker-no-usingoperation)`  
The `options.usingOperation` parameter is required when adding a new marker.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-addroot-root-exists">  
####  
`[writer-addroot-root-exists](#ckeditor5/latest/support/error-codes.html--error-writer-addroot-root-exists)`  
Root with provided name already exists and is attached.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-detachroot-no-root">  
####  
`[writer-detachroot-no-root](#ckeditor5/latest/support/error-codes.html--error-writer-detachroot-no-root)`  
Root with provided name does not exist or is already detached.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-incorrect-use">  
####  
`[writer-incorrect-use](#ckeditor5/latest/support/error-codes.html--error-writer-incorrect-use)`  
Trying to use a writer outside a [change()](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-change) or [enqueueChange()](../api/module%5Fengine%5Fmodel%5Fmodel-Model.html#function-enqueueChange:DEFAULT%5FBATCH) blocks.  
The writer can only be used inside these blocks which ensures that the model can only be changed during such "sessions".
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-merge-no-element-after">  
####  
`[writer-merge-no-element-after](#ckeditor5/latest/support/error-codes.html--error-writer-merge-no-element-after)`  
Node after merge position must be an element.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-merge-no-element-before">  
####  
`[writer-merge-no-element-before](#ckeditor5/latest/support/error-codes.html--error-writer-merge-no-element-before)`  
Node before merge position must be an element.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-move-different-document">  
####  
`[writer-move-different-document](#ckeditor5/latest/support/error-codes.html--error-writer-move-different-document)`  
Range is going to be moved within not the same document. Please use [insert](../api/module%5Fengine%5Fmodel%5Fwriter-ModelWriter.html#function-insert) instead.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-move-invalid-range">  
####  
`[writer-move-invalid-range](#ckeditor5/latest/support/error-codes.html--error-writer-move-invalid-range)`  
Invalid range to move.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-move-range-not-flat">  
####  
`[writer-move-range-not-flat](#ckeditor5/latest/support/error-codes.html--error-writer-move-range-not-flat)`  
Range to move is not flat.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-removemarker-no-marker">  
####  
`[writer-removemarker-no-marker](#ckeditor5/latest/support/error-codes.html--error-writer-removemarker-no-marker)`  
Trying to remove marker which does not exist.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-rename-not-element-instance">  
####  
`[writer-rename-not-element-instance](#ckeditor5/latest/support/error-codes.html--error-writer-rename-not-element-instance)`  
Trying to rename an object which is not an instance of Element.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-split-element-no-parent">  
####  
`[writer-split-element-no-parent](#ckeditor5/latest/support/error-codes.html--error-writer-split-element-no-parent)`  
Element with no parent cannot be split.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-split-invalid-limit-element">  
####  
`[writer-split-invalid-limit-element](#ckeditor5/latest/support/error-codes.html--error-writer-split-invalid-limit-element)`  
Limit element is not a position ancestor.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-unwrap-element-no-parent">  
####  
`[writer-unwrap-element-no-parent](#ckeditor5/latest/support/error-codes.html--error-writer-unwrap-element-no-parent)`  
Trying to unwrap an element which has no parent.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-marker-not-exists">  
####  
`[writer-updatemarker-marker-not-exists](#ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-marker-not-exists)`  
Marker with provided name does not exist and will not be updated.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-reconvert-using-editingcontroller">  
####  
`[writer-updatemarker-reconvert-using-editingcontroller](#ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-reconvert-using-editingcontroller)`  
The usage of `writer.updateMarker()` only to reconvert (refresh) a [model marker](../api/module%5Fengine%5Fmodel%5Fmarkercollection-Marker.html) was deprecated and may not work in the future. Please update your code to use [editor.editing.reconvertMarker()](../api/module%5Fengine%5Fcontroller%5Feditingcontroller-EditingController.html#function-reconvertMarker)instead.  
##### Parameters  
`markerName : any`  
The name of the updated marker.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-wrong-options">  
####  
`[writer-updatemarker-wrong-options](#ckeditor5/latest/support/error-codes.html--error-writer-updatemarker-wrong-options)`  
One of the options is required - provide range, usingOperations or affectsData.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-wrap-element-attached">  
####  
`[writer-wrap-element-attached](#ckeditor5/latest/support/error-codes.html--error-writer-wrap-element-attached)`  
Element to wrap with is already attached to a tree model.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-wrap-element-not-empty">  
####  
`[writer-wrap-element-not-empty](#ckeditor5/latest/support/error-codes.html--error-writer-wrap-element-not-empty)`  
Element to wrap with is not empty.
* <a id="ckeditor5/latest/support/error-codes.html--error-writer-wrap-range-not-flat">  
####  
`[writer-wrap-range-not-flat](#ckeditor5/latest/support/error-codes.html--error-writer-wrap-range-not-flat)`  
Range to wrap is not flat.

<a id="ckeditor5/latest/support/index.html">source file: "ckeditor5/latest/support/index.html"</a>

## Getting support

<a id="ckeditor5/latest/support/index.html--commercial-support">

### Commercial support

As a licensed customer, you benefit from direct support from the core CKEditor 5 development team. Our commercial licenses are tailored for professionals and enterprises. If you have any support requests, please [contact us](https://ckeditor.com/contact/).

For more information, check the [CKEditor 5 Pricing page](https://ckeditor.com/pricing/).

<a id="ckeditor5/latest/support/index.html--asking-questions">

### Asking questions

If you have questions about our products or features:

* If you are a customer or your questions relate to our premium features, please [contact us](https://ckeditor.com/contact/).
* If you have questions about the integration steps or best practices, you can [submit an issue](#ckeditor5/latest/support/index.html--submitting-an-issue). Please note that our response may take some time. Thank you for your understanding.

<a id="ckeditor5/latest/support/index.html--reporting-issues">

### Reporting issues

If you believe you have found an issue in CKEditor 5, we appreciate you letting us know. Before creating a bug report, please read the guidelines on how to do it properly and efficiently.

<a id="ckeditor5/latest/support/index.html--reproduce-on-official-examples">

#### Reproduce on official examples

To eliminate the possibility that the issue is caused by third-party software or your customizations, first try to reproduce the issue on the [official examples](#ckeditor5/latest/examples/index.html).

The examples are always running the latest editor version. Please note that if the problem was fixed in a release newer than the version you are using, you will need to upgrade your CKEditor 5 installation as we do not backport fixes.

Most issues are reproducible on the demo. If your case is different, follow the steps described below.

<a id="ckeditor5/latest/support/index.html--submitting-an-issue">

#### Submitting an issue

If you are a commercial customer, please reach us via our [support channel](https://ckeditor.com/contact/) for the fastest response.

We keep most of our issues on GitHub to provide open access to reported cases. To report a new issue, you will need a GitHub account.

Issues should be reported via the specific issue trackers:

* [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues).
* [Angular integration](https://github.com/ckeditor/ckeditor5-angular),
* [React integration](https://github.com/ckeditor/ckeditor5-react),
* [Vue integration](https://github.com/ckeditor/ckeditor5-vue),
* [CKEditor 5 inspector](https://github.com/ckeditor/ckeditor5-inspector).

Things to keep in mind:

* Search for existing issues before starting a new one. This helps our team keep the backlog organized.
* Be concise and informative to make it easy for our team to understand the problem.
* Feel free to join discussions around issues and share your opinion!

Issues with third-party plugins should be reported directly to their developers.

<a id="ckeditor5/latest/support/index.html--reporting-security-issues">

### Reporting security issues

If you believe you have found a security issue in the CKEditor 5 software, please contact us immediately.

When reporting a suspected security problem, please bear this in mind:

* Make sure to provide as many details as possible about the vulnerability.
* Please do not disclose publicly any security issues until we fix them and publish security releases.

Contact the security team at [security@cksource.com](mailto:security@cksource.com). As soon as we receive the security report, we will work promptly to confirm the issue and provide a security fix.

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html">source file: "ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html"</a>

## CKEditor 4 configuration options compatibility

The following table presents CKEditor 4 configuration options and, if available, their equivalent in CKEditor 5.

Note: In CKEditor 5, the number of options was reduced on purpose. Configuring CKEditor 4 was too troublesome due to the number of available configuration options (around 300). This is why when designing CKEditor 5 from scratch, we decided to come up with a simplified editor, with well-thought default behavior, based on the results of the [Editor Recommendations](http://ckeditor.github.io/editor-recommendations/) project.

| CKEditor 4                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | CKEditor 5                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [allowedContent](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-allowedContent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | You can extend the list of HTML tags or attributes that CKEditor 5 should support via the [GHS (General HTML Support) feature](#ckeditor5/latest/features/html/general-html-support.html). The GHS allows adding HTML markup not yet covered by official CKEditor 5 features into the editor's content. Such elements can be loaded, pasted, or output. It does not, however, provide a dedicated UI for the extended HTML markup. You can get full-fledged HTML support by writing a plugin that (ideally) provides also means to control (insert, edit, delete) such markup. For more information on how to create plugins check the [Creating a basic plugin](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html) article. Looking at the source code of CKEditor 5 plugins may also give you a lot of inspiration. CKEditor 5 will only preserve content that is explicitly converted between the model and the view by the editor plugins. Check the [conversion documentation](#ckeditor5/latest/framework/deep-dive/conversion/intro.html) to learn how to extend the conversion rules. |
| [applicationTitle](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-applicationTitle)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [autoEmbed\_widget](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoEmbed%5Fwidget)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Refer to the [Media embed](#ckeditor5/latest/features/media-embed.html) feature guide to learn more about media embedding in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [autoGrow\_bottomSpace](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoGrow%5FbottomSpace) [autoGrow\_maxHeight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoGrow%5FmaxHeight) [autoGrow\_minHeight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoGrow%5FminHeight) [autoGrow\_onStartup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoGrow%5FonStartup)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | These settings are no longer needed as CKEditor 5 automatically grows with content by default. [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>. This means that you can control the height (and similar options) of the editing area with CSS. For example, you can set the minHeight and maxHeight options with the following code: .ck.ck-content:not(.ck-comment\_\_input \*) { 	/\* Note: You can use min-height and max-height instead here. \*/ 	height: 300px; 	overflow-y: auto; }                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [autoUpdateElement](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autoUpdateElement)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | CKEditor 5 always updates the replaced element. This behavior cannot be disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [autocomplete\_commitKeystrokes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autocomplete%5FcommitKeystrokes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [autolink\_commitKeystrokes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autolink%5FcommitKeystrokes) [autolink\_emailRegex](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autolink%5FemailRegex) [autolink\_urlRegex](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-autolink%5FurlRegex)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Refer to the [Autolink section](#ckeditor5/latest/features/link.html--autolink-feature) of the Link guide to learn more about support for automatic linking in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [baseFloatZIndex](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-baseFloatZIndex)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A. There is a dedicated [issue about z-index management](https://github.com/ckeditor/ckeditor5/issues/5352) and making it more open for developers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [baseHref](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-baseHref)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Not supported yet, see [the relevant GitHub issue](https://github.com/ckeditor/ckeditor5/issues/665).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [basicEntities](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-basicEntities)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [blockedKeystrokes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-blockedKeystrokes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [bodyClass](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-bodyClass)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>, so this setting is no longer needed. Wrap the editor with a <div class="..."> to achieve a similar result. When using [balloon](#ckeditor5/latest/examples/builds/balloon-editor.html), [balloon block](#ckeditor5/latest/examples/builds/balloon-block-editor.html), [inline](#ckeditor5/latest/examples/builds/inline-editor.html), or [decoupled](#ckeditor5/latest/examples/builds/document-editor.html) editor, you may add a class to the element on which the editor is initialized. Additionally, all editor types use .ck-content on their main root editable elements. This class can thus also be used to write style sheet rules for the editor content.                                                                                                                                                                                                                                                                                                      |
| [bodyId](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-bodyId)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>, so this setting is no longer needed. Wrap the editor with a <div id="..."> to achieve a similar result. When using [balloon](#ckeditor5/latest/examples/builds/balloon-editor.html), [balloon block](#ckeditor5/latest/examples/builds/balloon-block-editor.html), [inline](#ckeditor5/latest/examples/builds/inline-editor.html), or [decoupled](#ckeditor5/latest/examples/builds/document-editor.html) editor, you may add a class to the element on which the editor is initialized. Additionally, all editor types use .ck-content on their main root editable elements. This class can thus also be used to write style sheet rules for the editor content.                                                                                                                                                                                                                                                                                                         |
| [browserContextMenuOnCtrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-browserContextMenuOnCtrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | No longer needed as CKEditor 5 does not have a context menu and does not block the native browser context menu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [clipboard\_defaultContentType](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-clipboard%5FdefaultContentType) [clipboard\_handleImages](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-clipboard%5FhandleImages) [clipboard\_notificationDuration](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-clipboard%5FnotificationDuration)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [cloudServices\_tokenUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-cloudServices%5FtokenUrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | See [config.cloudServices.tokenUrl](../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [cloudServices\_uploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-cloudServices%5FuploadUrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | See [config.cloudServices.uploadUrl](../../api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-uploadUrl). Check out the comprehensive [Image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html) guide to learn more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [codeSnippetGeshi\_url](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-codeSnippetGeshi%5Furl) [codeSnippet\_codeClass](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-codeSnippet%5FcodeClass) [codeSnippet\_languages](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-codeSnippet%5Flanguages) [codeSnippet\_theme](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-codeSnippet%5Ftheme)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Refer to the [Code block](#ckeditor5/latest/features/code-blocks.html) feature guide to learn more about support for blocks of pre-formatted code in CKEditor 5. A plugin adding support for the inline <code> element is included in the [Basic styles](#ckeditor5/latest/features/basic-styles.html) package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [colorButton\_backStyle](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FbackStyle) [colorButton\_colors](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5Fcolors) [colorButton\_colorsPerRow](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FcolorsPerRow) [colorButton\_contentsCss](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FcontentsCss) [colorButton\_enableAutomatic](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FenableAutomatic) [colorButton\_enableMore](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FenableMore) [colorButton\_foreStyle](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FforeStyle) [colorButton\_historyRowLimit](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FhistoryRowLimit) [colorButton\_normalizeBackground](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FnormalizeBackground) [config.colorButton\_renderContentColors](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-colorButton%5FrenderContentColors)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Refer to the [Font family, size, and color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features) feature guide to learn more about configuring font and background color in CKEditor 5. CKEditor 5 also provides a new highlight plugin. It allows for highlighting parts of the text with the <mark> element with different CSS classes that can be styled. See the [Highlight](#ckeditor5/latest/features/highlight.html) feature guide for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [contentsCss](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-contentsCss)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>, so such file and configuration setting is no longer needed. If for some reason you need to style the contents of the editing area differently, use the .ck-content selector.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [contentsLangDirection](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-contentsLangDirection)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Refer to the [Setting the language of the content](#ckeditor5/latest/getting-started/setup/ui-language.html--setting-the-language-of-the-content) guide to learn how to set the content direction using the [config.language](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-language) configuration option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [contentsLanguage](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-contentsLanguage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Refer to the [Setting the language of the content](#ckeditor5/latest/getting-started/setup/ui-language.html--setting-the-language-of-the-content) guide to learn how to set the content language using the [config.language](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-language) configuration option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [contextmenu\_contentsCss](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-contextmenu%5FcontentsCss)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | No longer needed as CKEditor 5 does not have a context menu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [copyFormatting\_allowRules](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FallowRules) [copyFormatting\_allowedContexts](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FallowedContexts) [copyFormatting\_disallowRules](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FdisallowRules) [copyFormatting\_keystrokeCopy](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FkeystrokeCopy) [copyFormatting\_keystrokePaste](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FkeystrokePaste) [copyFormatting\_outerCursor](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-copyFormatting%5FouterCursor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Refer to the [Format painter](#ckeditor5/latest/features/format-painter.html) guide to learn how the copy formatting functionality works in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [coreStyles\_bold](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Fbold)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | CKEditor 5 uses the <strong> element, see [Editor Recommendations - Bold](https://ckeditor.github.io/editor-recommendations/features/bold.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [coreStyles\_italic](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Fitalic)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | CKEditor 5 uses the <i> element, see [Editor Recommendations - Italic](https://ckeditor.github.io/editor-recommendations/features/italic.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [coreStyles\_strike](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Fstrike)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | CKEditor 5 uses the <s> element, see [Editor Recommendations - Strikethrough](https://ckeditor.github.io/editor-recommendations/features/strikethrough.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [coreStyles\_subscript](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Fsubscript)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | CKEditor 5 uses the <sub> element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [coreStyles\_superscript](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Fsuperscript)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | CKEditor 5 uses the <sup> element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [coreStyles\_toggleSubSup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5FtoggleSubSup)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | In CKEditor 5 it is possible to apply subscript and superscript to the same element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [coreStyles\_underline](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-coreStyles%5Funderline)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | CKEditor 5 uses the <u> element, see [Editor Recommendations - Underline](https://github.com/ckeditor/editor-recommendations/issues/4).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [customConfig](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-customConfig)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | For performance reasons, CKEditor 5 no longer loads a separate configuration file. Passing configuration options inline reduces the number of HTTP requests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [dataIndentationChars](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dataIndentationChars)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [defaultLanguage](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-defaultLanguage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | The support for multiple translations is handled by the translations service. See the [UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [delayIfDetached](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-delayIfDetached) [delayIfDetached\_callback](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-delayIfDetached%5Fcallback) [delayIfDetached\_interval](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-delayIfDetached%5Finterval)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [devtools\_styles](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-devtools%5Fstyles) [devtools\_textCallback](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-devtools%5FtextCallback)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | The old CKEditor 4 Developer Tools plugin is not available for CKEditor 5\. However, check out the new [CKEditor 5 inspector](#ckeditor5/latest/framework/develpment-tools/inspector.html). It is a far more advanced tool that will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [dialog\_backgroundCoverColor](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FbackgroundCoverColor) [dialog\_backgroundCoverOpacity](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FbackgroundCoverOpacity)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | The use of configuration options to style selected parts of the editor was dropped in favor of much more powerful [theme customization](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [dialog\_buttonsOrder](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FbuttonsOrder) [dialog\_magnetDistance](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FmagnetDistance) [dialog\_noConfirmCancel](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FnoConfirmCancel) [dialog\_startupFocusTab](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-dialog%5FstartupFocusTab)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [disableNativeSpellChecker](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-disableNativeSpellChecker)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Note: An official integration of the spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, [WProofreader](#ckeditor5/latest/features/spelling-and-grammar-checking.html). A dedicated configuration option to disable the native browser spell checker is unavailable. However, in case of inline, balloon, and balloon block editors it can be done by setting the [spellcheck](https://developer.mozilla.org/en-US/docs/Web/HTML/Global%5Fattributes/spellcheck) attribute directly on the element where CKEditor should be enabled. Additionally, for all types of editors, including the classic and decoupled ones, you can also call: editor.editing.view.change( writer => { 	writer.setAttribute( 'spellcheck', 'false', editor.editing.view.document.getRoot() ); } );                                                                                                                                                                                                                                                                                                    |
| [disableNativeTableHandles](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-disableNativeTableHandles)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [disableObjectResizing](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-disableObjectResizing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [disableReadonlyStyling](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-disableReadonlyStyling)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [disallowedContent](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-disallowedContent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | See [config.allowedContent](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--allowedContent). No longer needed as CKEditor 5 removes all unwanted markup that cannot be edited with the editor. You can control this by adding plugins to the editor or via the [General HTML Support feature](#ckeditor5/latest/features/html/general-html-support.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [div\_wrapTable](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-div%5FwrapTable)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [docType](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-docType)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A. CKEditor 5 no longer encapsulates the editing area in an <iframe>, so the editor is using the same DOCTYPE as the page where it operates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [easyimage\_class](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-easyimage%5Fclass) [easyimage\_defaultStyle](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-easyimage%5FdefaultStyle) [easyimage\_styles](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-easyimage%5Fstyles) [easyimage\_toolbar](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-easyimage%5Ftoolbar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Refer to the [Images](#ckeditor5/latest/features/images/images-overview.html) feature guides to learn more about image-related features in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [editorplaceholder](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-editorplaceholder) [editorplaceholder\_delay](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-editorplaceholder%5Fdelay)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Refer to the [Editor placeholder](#ckeditor5/latest/features/editor-placeholder.html) feature guide to learn more about configuring this feature in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [emailProtection](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-emailProtection)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [embed\_provider](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-embed%5Fprovider)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Refer to the [Media embed](#ckeditor5/latest/features/media-embed.html) feature guide to learn more about media embedding in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [emoji\_emojiListUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-emoji%5FemojiListUrl) [emoji\_followingSpace](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-emoji%5FfollowingSpace) [emoji\_minChars](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-emoji%5FminChars)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | You can paste emoji into CKEditor 5 as Unicode content. You can also use the emoji picker of your operating system to insert emoji characters. Use the Ctrl+Cmd+Space keyboard shortcut (macOS) or Win+. (Windows) or the relevant emoji key on the touch keyboard of your device to open the picker. You can configure the [automatic text transformation feature](#ckeditor5/latest/features/text-transformation.html) to deliver emojis with shortcodes, too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [enableContextMenu](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-enableContextMenu)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A. CKEditor 5 does not come with a context menu. A configurable contextual inline toolbar is preferred instead to offer contextual actions for features such as [tables](#ckeditor5/latest/features/tables/tables.html--table-contextual-toolbar) or [images](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar). See also [toolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [enableTabKeyTools](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-enableTabKeyTools)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [enterMode](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-enterMode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A. CKEditor 5 always creates a new paragraph (<p> element) as specified by [Editor Recommendations - Enter key](http://ckeditor.github.io/editor-recommendations/usability/enter-key.html). You can use Shift+Enter for creating soft line breaks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [entities](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-entities) [entities\_additional](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-entities%5Fadditional) [entities\_greek](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-entities%5Fgreek) [entities\_latin](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-entities%5Flatin) [entities\_processNumerical](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-entities%5FprocessNumerical)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [exportPdf\_fileName](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-exportPdf%5FfileName) [exportPdf\_options](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-exportPdf%5Foptions) [exportPdf\_service](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-exportPdf%5Fservice) [exportPdf\_stylesheets](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-exportPdf%5Fstylesheets) [exportPdf\_tokenUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-exportPdf%5FtokenUrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Refer to the [Export to PDF feature](#ckeditor5/latest/features/converters/export-pdf.html) guide to learn more about configuring the HTML to PDF converter in CKEditor 5\.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [extraAllowedContent](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-extraAllowedContent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | See [config.allowedContent](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--allowedContent). You can also achieve this via the [General HTML Support feature](#ckeditor5/latest/features/html/general-html-support.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [extraPlugins](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-extraPlugins)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Learn how to [install plugins in CKEditor 5](#ckeditor5/latest/getting-started/setup/configuration.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [fileTools\_defaultFileName](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fileTools%5FdefaultFileName) [fileTools\_requestHeaders](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fileTools%5FrequestHeaders)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [filebrowserBrowseUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserBrowseUrl) [filebrowserFlashBrowseUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserFlashBrowseUrl) [filebrowserFlashUploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserFlashUploadUrl) [filebrowserImageBrowseLinkUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserImageBrowseLinkUrl) [filebrowserImageBrowseUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserImageBrowseUrl) [filebrowserImageUploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserImageUploadUrl) [filebrowserUploadMethod](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserUploadMethod) [filebrowserUploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserUploadUrl) [filebrowserWindowFeatures](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserWindowFeatures) [filebrowserWindowHeight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserWindowHeight) [filebrowserWindowWidth](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-filebrowserWindowWidth)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | There is no equivalent of the file browser plugin in CKEditor 5 yet. See also [config.uploadUrl](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--uploadUrl).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [fillEmptyBlocks](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fillEmptyBlocks)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Blocks are always filled in CKEditor 5 because this preserves the intention of the content author (who left such empty lines) in the output data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [find\_highlight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-find%5Fhighlight)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Refer to the [Find and replace](#ckeditor5/latest/features/find-and-replace.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [flashAddEmbedTag](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-flashAddEmbedTag) [flashConvertOnEdit](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-flashConvertOnEdit) [flashEmbedTagOnly](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-flashEmbedTagOnly)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [floatSpaceDockedOffsetX](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-floatSpaceDockedOffsetX) [floatSpaceDockedOffsetY](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-floatSpaceDockedOffsetY) [floatSpacePinnedOffsetX](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-floatSpacePinnedOffsetX) [floatSpacePinnedOffsetY](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-floatSpacePinnedOffsetY) [floatSpacePreferRight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-floatSpacePreferRight)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [fontSize\_defaultLabel](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fontSize%5FdefaultLabel) [fontSize\_sizes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fontSize%5Fsizes) [fontSize\_style](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fontSize%5Fstyle) [font\_defaultLabel](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-font%5FdefaultLabel) [font\_names](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-font%5Fnames) [font\_style](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-font%5Fstyle)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Refer to the [Font family, size, and color](#ckeditor5/latest/features/font.html) feature guide to learn more about font size, family, and color support in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [forceEnterMode](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-forceEnterMode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | N/A. Se also [config.enterMode](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--enterMode).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [forcePasteAsPlainText](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-forcePasteAsPlainText)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A. No longer needed as CKEditor 5 removes all unwanted markup that cannot be edited with the enabled editor plugins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [forceSimpleAmpersand](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-forceSimpleAmpersand)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [format\_address](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Faddress) [format\_div](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fdiv) [format\_p](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fp) [format\_pre](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fpre)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [format\_h1](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh1) [format\_h2](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh2) [format\_h3](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh3) [format\_h4](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh4) [format\_h5](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh5) [format\_h6](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Fh6)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | All headings are configurable via [config.heading.options](../../api/module%5Fheading%5Fheadingconfig-HeadingConfig.html#member-options). See also the [Headings](#ckeditor5/latest/features/headings.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [format\_tags](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-format%5Ftags)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | To enable additional block tags in CKEditor 5, you may use the [General HTML Support feature](#ckeditor5/latest/features/html/general-html-support.html). Alternatively, you must provide a dedicated plugin. See also [config.allowedContent](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--allowedContent).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [fullPage](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fullPage)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Available through the [FullPage](../../api/module%5Fhtml-support%5Ffullpage-FullPage.html) API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [grayt\_autoStartup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-grayt%5FautoStartup)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | An official integration of the spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, [WProofreader](#ckeditor5/latest/features/spelling-and-grammar-checking.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [height](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-height)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>. This means that you can control the height (and similar options) of the editing area with CSS. For example, you can set the height with .ck-editor\_\_editable\_inline { height:400px; }. To set the height dynamically (from JavaScript), use the view writer: editor.editing.view.change( writer => {     writer.setStyle( 'height', '400px', editor.editing.view.document.getRoot() ); } ); See also [How to set the height of CKEditor 5 (Classic editor)](https://stackoverflow.com/questions/46559354/how-to-set-the-height-of-ckeditor-5-classic-editor).                                                                                                                                                                                                                                                                                                                                                                                                          |
| [htmlEncodeOutput](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-htmlEncodeOutput)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A. CKEditor 5 outputs HTML markup. See also [this StackOverflow question](https://stackoverflow.com/questions/47555667/ckeditor-5-htmlencodeoutput-doesnt-work) and a [dedicated issue](https://github.com/ckeditor/ckeditor5/issues/698).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [ignoreEmptyParagraph](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-ignoreEmptyParagraph)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [image2\_alignClasses](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FalignClasses)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Available via more powerful [config.image.styles](../../api/module%5Fimage%5Fimageconfig-ImageConfig.html#member-styles). This also allows for using custom style definitions, not just left, right, and center alignment. See the [Image styles](#ckeditor5/latest/features/images/images-styles.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [image2\_altRequired](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FaltRequired) [image2\_captionedClass](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FcaptionedClass) [image2\_defaultLockRatio](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FdefaultLockRatio) [image2\_disableResizer](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FdisableResizer) [image2\_maxSize](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FmaxSize) [image2\_prefillDimensions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image2%5FprefillDimensions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Refer to the [Image](#ckeditor5/latest/features/images/images-overview.html) feature guide to learn more about image-related features and customization options in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [imageUploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-imageUploadUrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | See [config.uploadUrl](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--uploadUrl).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [image\_prefillDimensions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image%5FprefillDimensions) [image\_previewText](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image%5FpreviewText) [image\_removeLinkByEmptyURL](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-image%5FremoveLinkByEmptyURL)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Refer to the [Image](#ckeditor5/latest/features/images/images-overview.html) feature guide to learn more about image-related features and customization options in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [indentClasses](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-indentClasses) [indentOffset](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-indentOffset) [indentUnit](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-indentUnit)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Refer to the [Configuring the block indentation](#ckeditor5/latest/features/indent.html--configuring-the-block-indentation-feature) feature guide to learn how to customize the indentation behavior using offsets, units, or classes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [jqueryOverrideVal](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-jqueryOverrideVal)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [justifyClasses](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-justifyClasses)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Refer to the [Text alignment](#ckeditor5/latest/features/text-alignment.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [keystrokes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-keystrokes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | You can register keystroke handlers using [EditingKeystrokeHandler](../../api/module%5Fcore%5Feditingkeystrokehandler-EditingKeystrokeHandler.html). You can find more information and examples in a dedicated [Keystrokes and focus management](#ckeditor5/latest/framework/architecture/ui-library.html--keystrokes-and-focus-management) section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [language](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-language) [language\_list](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-language%5Flist)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | The support for many translations is handled by the translations service. See the [UI language](#ckeditor5/latest/getting-started/setup/ui-language.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [linkDefaultProtocol](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkDefaultProtocol)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [config.link.defaultProtocol](../../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-defaultProtocol)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [linkJavaScriptLinksAllowed](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkJavaScriptLinksAllowed)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [linkPhoneMsg](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkPhoneMsg) [linkPhoneRegExp](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkPhoneRegExp)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [linkShowAdvancedTab](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkShowAdvancedTab)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Refer to the [Link](#ckeditor5/latest/features/link.html) feature guide to read about setting custom link attributes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [linkShowTargetTab](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-linkShowTargetTab)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | See [config.link.addTargetToExternalLinks](../../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-addTargetToExternalLinks)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [magicline\_color](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5Fcolor) [magicline\_everywhere](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5Feverywhere) [magicline\_holdDistance](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5FholdDistance) [magicline\_keystrokeNext](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5FkeystrokeNext) [magicline\_keystrokePrevious](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5FkeystrokePrevious) [magicline\_tabuList](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5FtabuList) [magicline\_triggerOffset](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-magicline%5FtriggerOffset)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | This functionality is covered by the [WidgetTypeAround](../../api/module%5Fwidget%5Fwidgettypearound%5Fwidgettypearound-WidgetTypeAround.html) plugin. It allows users to type around widgets where normally it is impossible to place the caret due to limitations of web browsers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [mathJaxClass](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-mathJaxClass) [mathJaxLib](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-mathJaxLib)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | N/A. Math equation functionality for CKEditor 5 is provided by a partner solution, [MathType](#ckeditor5/latest/features/math-equations.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [maximize\_historyIntegration](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-maximize%5FhistoryIntegration)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [mentions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-mentions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Refer to the [Mentions](#ckeditor5/latest/features/mentions.html) feature guide to learn more about smart autocompletion based on user input in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [menu\_groups](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-menu%5Fgroups) [menu\_subMenuDelay](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-menu%5FsubMenuDelay)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | CKEditor 5 does not come with a context menu. A configurable contextual inline toolbar is preferred instead to offer contextual actions for features such as [tables](#ckeditor5/latest/features/tables/tables.html--table-contextual-toolbar) or [images](#ckeditor5/latest/features/images/images-overview.html--image-contextual-toolbar). See also [toolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [newpage\_html](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-newpage%5Fhtml)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [notification\_duration](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-notification%5Fduration)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [observableParent](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-observableParent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [on](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-on)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Using the configuration file or setting to define event listeners was a bad practice so support for it was dropped. When creating an editor, a Promise is returned. Use then/catch() to define a callback when the editor is initialized or fails to start. The promise returns the created editor instance, for example, [ClassicEditor](../../api/module%5Feditor-classic%5Fclassiceditor-ClassicEditor.html), on which you can listen to its events. Note: The editor instance is not the only object on which events are fired. You can also listen to, for example, [Document](../../api/module%5Fengine%5Fmodel%5Fdocument-ModelDocument.html) events.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [pasteFilter](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFilter)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Not needed as CKEditor 5 always trims the pasted content to match what the available plugins can handle. If you would like to filter the pasted content even further, [report a ticket](https://github.com/ckeditor/ckeditor5/issues/new?labels=type%3Afeature&template=2-feature-request.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [pasteFromWordCleanupFile](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWordCleanupFile) [pasteFromWordNumberedHeadingToList](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWordNumberedHeadingToList) [pasteFromWordPromptCleanup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWordPromptCleanup) [pasteFromWordRemoveStyles](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWordRemoveStyles) [pasteFromWord\_heuristicsEdgeList](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWord%5FheuristicsEdgeList) [pasteFromWord\_inlineImages](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteFromWord%5FinlineImages)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Refer to the [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) feature guide to learn more about support for pasting from Microsoft Word in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [pasteTools\_keepZeroMargins](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-pasteTools%5FkeepZeroMargins)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Refer to the [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) and [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html) feature guides to learn more about support for pasting from external applications in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [plugins](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-plugins)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | See the [plugins](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-plugins) configuration option. The way how plugins are enabled in CKEditor 5 has changed in general. Check the articles about [plugins](#ckeditor5/latest/framework/architecture/plugins.html) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [protectedSource](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-protectedSource)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [readOnly](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-readOnly)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | See [editor.isReadOnly](../../api/module%5Fcore%5Feditor%5Feditor-Editor.html#member-isReadOnly) and refer to the [Read-only](#ckeditor5/latest/features/read-only.html) feature guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [removeButtons](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-removeButtons)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A. You can achieve a similar effect by setting the [toolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar) option with fewer buttons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [removeDialogTabs](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-removeDialogTabs)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [removeFormatAttributes](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-removeFormatAttributes) [removeFormatTags](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-removeFormatTags)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Refer to the [Remove formatting](#ckeditor5/latest/features/remove-format.html) feature guide to learn how to remove any text formatting applied with inline HTML elements and CSS styles in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [removePlugins](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-removePlugins)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | See [config.removePlugins](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-removePlugins).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [resize\_dir](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5Fdir) [resize\_enabled](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5Fenabled) [resize\_maxHeight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5FmaxHeight) [resize\_maxWidth](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5FmaxWidth) [resize\_minHeight](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5FminHeight) [resize\_minWidth](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-resize%5FminWidth)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No longer needed. The editor automatically grows with content. You can also limit its height with min-height and max-height or set it with height if you need. If you want to allow the users to manually resize the editor, you need to implement this behavior by yourself.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [scayt\_autoStartup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FautoStartup) [scayt\_contextCommands](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FcontextCommands) [scayt\_contextMenuItemsOrder](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FcontextMenuItemsOrder) [scayt\_customDictionaryIds](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FcustomDictionaryIds) [scayt\_customPunctuation](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FcustomPunctuation) [scayt\_customerId](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FcustomerId) [scayt\_disableOptionsStorage](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FdisableOptionsStorage) [scayt\_elementsToIgnore](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FelementsToIgnore) [scayt\_handleCheckDirty](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FhandleCheckDirty) [scayt\_handleUndoRedo](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FhandleUndoRedo) [scayt\_ignoreAllCapsWords](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FignoreAllCapsWords) [scayt\_ignoreDomainNames](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FignoreDomainNames) [scayt\_ignoreWordsWithMixedCases](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FignoreWordsWithMixedCases) [scayt\_ignoreWordsWithNumbers](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FignoreWordsWithNumbers) [scayt\_inlineModeImmediateMarkup](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FinlineModeImmediateMarkup) [scayt\_maxSuggestions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FmaxSuggestions) [scayt\_minWordLength](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FminWordLength) [scayt\_moreSuggestions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FmoreSuggestions) [scayt\_sLang](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FsLang) [scayt\_serviceHost](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FserviceHost) [scayt\_servicePath](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FservicePath) [scayt\_servicePort](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FservicePort) [scayt\_serviceProtocol](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FserviceProtocol) [scayt\_srcUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FsrcUrl) [scayt\_uiTabs](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FuiTabs) [scayt\_userDictionaryName](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-scayt%5FuserDictionaryName) | The spell and grammar checking functionality for CKEditor 5 is provided by a partner solution, [WProofreader](#ckeditor5/latest/features/spelling-and-grammar-checking.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [sharedSpaces](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-sharedSpaces)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A. The [decoupled editor](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) allows configuring where to insert the toolbar and the editable element. In addition to that, CKEditor 5 Framework architecture allows for writing a custom editor that contains many editable elements (document roots). See the [multi-root editor example](#ckeditor5/latest/examples/builds/multi-root-editor.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [shiftEnterMode](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-shiftEnterMode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | N/A. CKEditor 5 always creates a new paragraph (<p> element) as specified by [Editor Recommendations - Enter key](http://ckeditor.github.io/editor-recommendations/usability/enter-key.html). You can use Shift+Enter for creating soft line breaks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [shiftLineBreaks](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-shiftLineBreaks)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A. CKEditor 5 always moves line breaks (<br> elements) outside inline elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [skin](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-skin)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | In CKEditor 5 you can make lots of changes to the interface by changing the default CKEditor theme. See the [Theme customization](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) guide. For heavy UI modifications, like integrating CKEditor with a custom UI framework, you need to build a custom editor. See the [Third-party UI](#ckeditor5/latest/framework/deep-dive/ui/external-ui.html) guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [smiley\_columns](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-smiley%5Fcolumns) [smiley\_descriptions](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-smiley%5Fdescriptions) [smiley\_images](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-smiley%5Fimages) [smiley\_path](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-smiley%5Fpath)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | There is no dedicated smiley plugin in CKEditor 5\. However, you can paste the [emoji](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html--emoji) into the rich-text editor as Unicode content. You can also configure the [automatic text transformation feature](#ckeditor5/latest/features/text-transformation.html) to deliver Unicode emojis with shortcodes. You can use the [special characters](#ckeditor5/latest/features/special-characters.html) feature to input emojis as well.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [sourceAreaTabSize](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-sourceAreaTabSize)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [specialChars](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-specialChars)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Refer to the [Special characters](#ckeditor5/latest/features/special-characters.html) feature guide to learn more about support for inserting special characters in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [startupFocus](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-startupFocus)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [startupMode](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-startupMode)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [startupOutlineBlocks](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-startupOutlineBlocks)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [startupShowBorders](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-startupShowBorders)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [stylesSet](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-stylesSet)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Refer to the [Styles](#ckeditor5/latest/features/style.html) feature guide to learn more about applying styles to the editor content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [stylesheetParser\_skipSelectors](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-stylesheetParser%5FskipSelectors) [stylesheetParser\_validSelectors](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-stylesheetParser%5FvalidSelectors)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [tabIndex](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-tabIndex)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [tabletools\_scopedHeaders](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-tabletools%5FscopedHeaders)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [tabSpaces](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-tabSpaces)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [templates](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-templates) [templates\_files](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-templates%5Ffiles) [templates\_replaceContent](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-templates%5FreplaceContent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Refer to the [Templates](#ckeditor5/latest/features/template.html) guide to learn about support for templates in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [title](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-title)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [toolbar](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | See [config.toolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar). Refer to the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) feature guide to learn more about managing toolbars in CKEditor 5. See also [config.balloonToolbar](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-balloonToolbar) to define the toolbar of a balloon editor and the [block toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar) feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [toolbarCanCollapse](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbarCanCollapse)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | N/A. The user cannot collapse the toolbar manually. For distraction-free editing with the toolbar appearing when you need it, use [inline](#ckeditor5/latest/examples/builds/inline-editor.html), [balloon](#ckeditor5/latest/examples/builds/balloon-editor.html), or [balloon block](#ckeditor5/latest/examples/builds/balloon-block-editor.html) editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [toolbarGroupCycling](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbarGroupCycling) [toolbarGroups](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbarGroups)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | N/A. [The toolbar buttons can be grouped](../../api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-toolbar) by using '\|' as a separator or divided into lines by using '-'. Refer to the [toolbar](#ckeditor5/latest/getting-started/setup/toolbar.html) guide to learn more about managing toolbar items behavior in CKEditor 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [toolbarLocation](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbarLocation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N/A. You can achieve this by using the [decoupled editor](../../api/module%5Feditor-decoupled%5Fdecouplededitor-DecoupledEditor.html) or writing an editor with a customized UI view, like in this [editor with bottom toolbar](#ckeditor5/latest/examples/framework/bottom-toolbar-editor.html).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [toolbarStartupExpanded](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-toolbarStartupExpanded)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [uiColor](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-uiColor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | CKEditor 5 comes with an idea of much more powerful themes, where you can style almost every aspect of the UI. See the [Theme customization](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) guide and [Theme customization example](#ckeditor5/latest/examples/framework/theme-customization.html). Thanks to [CSS variables](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html--customization-with-css-variables) rebuilding the editor is not needed to change its styles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [undoStackSize](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-undoStackSize)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | See [config.typing.undoStep](../../api/module%5Ftyping%5Ftypingconfig-TypingConfig.html#member-undoStep).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [uploadUrl](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-uploadUrl)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | There are several image upload strategies supported by CKEditor 5\. Check out the [Image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html) guide to learn more.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [useComputedState](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-useComputedState)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N/A                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [widget\_keystrokeInsertLineAfter](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-widget%5FkeystrokeInsertLineAfter) [widget\_keystrokeInsertLineBefore](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-widget%5FkeystrokeInsertLineBefore)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | In CKEditor 5 you can insert a new paragraph directly after a widget with Enter and directly before a widget – with Shift \+ Enter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [width](/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-width)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) in CKEditor 5 no longer encapsulates the editing area in an <iframe>. This means that you can control the width (and similar options) of the editing area with CSS. For instance, to set the width of any of the editor types, use .ck-editor\_\_editable\_inline { width:400px; }. To set the width dynamically (from JavaScript), use the view writer: editor.editing.view.change( writer => {     writer.setStyle( 'width', '400px', editor.editing.view.document.getRoot() ); } ); See also [How to set the height of CKEditor 5 (Classic editor)](https://stackoverflow.com/questions/46559354/how-to-set-the-height-of-ckeditor-5-classic-editor).                                                                                                                                                                                                                                                                                                                                                                                        |

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-plugin-compatibility.html">source file: "ckeditor5/latest/updating/ckeditor4/ckeditor4-plugin-compatibility.html"</a>

## CKEditor 4 plugin equivalents

The following table presents plugins available in CKEditor 4 and their equivalent in CKEditor 5.

| **CKEditor 4**                                                                   | **CKEditor 5**                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [a11yhelp](https://ckeditor.com/cke4/addon/a11yhelp)                             | N/A                                                                                                                                                                                                                                   |
| [about](https://ckeditor.com/cke4/addon/about)                                   | N/A                                                                                                                                                                                                                                   |
| [ajax](https://ckeditor.com/cke4/addon/ajax)                                     | N/A                                                                                                                                                                                                                                   |
| [autocomplete](https://ckeditor.com/cke4/addon/autocomplete)                     | Partially covered by [Mentions](#ckeditor5/latest/features/mentions.html)                                                                                                                                                             |
| [autoembed](https://ckeditor.com/cke4/addon/autoembed)                           | [Auto media embed](#ckeditor5/latest/features/media-embed.html--automatic-media-embed-on-paste)                                                                                                                                       |
| [autogrow](https://ckeditor.com/cke4/addon/autogrow)                             | Core (see [Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) and [setting its height](https://ckeditor.com/docs/ckeditor5/latest/support/faq.html#how-to-set-the-height-of-ckeditor-5))                          |
| [autolink](https://ckeditor.com/cke4/addon/autolink)                             | [Autolink](#ckeditor5/latest/features/link.html--autolink-feature)                                                                                                                                                                    |
| [balloonpanel](https://ckeditor.com/cke4/addon/balloonpanel)                     | [Balloon panel view](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fpanel%5Fballoon%5Fballoonpanelview-BalloonPanelView.html)                                                                                           |
| [balloontoolbar](https://ckeditor.com/cke4/addon/balloontoolbar)                 | [Contextual balloon](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fpanel%5Fballoon%5Fcontextualballoon-ContextualBalloon.html)                                                                                         |
| [basicstyles](https://ckeditor.com/cke4/addon/basicstyles)                       | [Basic styles](#ckeditor5/latest/features/basic-styles.html)                                                                                                                                                                          |
| [bbcode](https://ckeditor.com/cke4/addon/bbcode)                                 | N/A                                                                                                                                                                                                                                   |
| [bidi](https://ckeditor.com/cke4/addon/bidi)                                     | Partially available [via configuration](https://ckeditor.com/docs/ckeditor5/latest/features/ui-language.html#righttoleft-rtl-languages-support) and the [Language plugin](#ckeditor5/latest/features/language.html)                   |
| [blockquote](https://ckeditor.com/cke4/addon/blockquote)                         | [Block quote](#ckeditor5/latest/features/block-quote.html)                                                                                                                                                                            |
| [button](https://ckeditor.com/cke4/addon/button)                                 | [Button view](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fbutton%5Fbuttonview-ButtonView.html)                                                                                                                       |
| [ckfinder](https://ckeditor.com/cke4/addon/ckfinder)                             | [CKFinder](#ckeditor5/latest/features/file-management/ckfinder.html)                                                                                                                                                                  |
| [clipboard](https://ckeditor.com/cke4/addon/clipboard)                           | [Clipboard](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fclipboard%5Fclipboard-Clipboard.html)                                                                                                                             |
| [cloudservices](https://ckeditor.com/cke4/addon/cloudservices)                   | [Cloud Services](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservices-CloudServices.html)                                                                                                           |
| [codesnippet](https://ckeditor.com/cke4/addon/codesnippet)                       | Partially covered by [Code blocks](#ckeditor5/latest/features/code-blocks.html)                                                                                                                                                       |
| [codesnippetgeshi](https://ckeditor.com/cke4/addon/codesnippetgeshi)             | N/A                                                                                                                                                                                                                                   |
| [colorbutton](https://ckeditor.com/cke4/addon/colorbutton)                       | [Font color and Font background color](#ckeditor5/latest/features/font.html--configuring-the-font-color-and-font-background-color-features)                                                                                           |
| [colordialog](https://ckeditor.com/cke4/addon/colordialog)                       | N/A                                                                                                                                                                                                                                   |
| [contextmenu](https://ckeditor.com/cke4/addon/contextmenu)                       | N/A                                                                                                                                                                                                                                   |
| [copyformatting](https://ckeditor.com/cke4/addon/copyformatting)                 | [Format painter](#ckeditor5/latest/features/format-painter.html)                                                                                                                                                                      |
| [devtools](https://ckeditor.com/cke4/addon/devtools)                             | N/A                                                                                                                                                                                                                                   |
| [dialog](https://ckeditor.com/cke4/addon/dialog)                                 | N/A                                                                                                                                                                                                                                   |
| [dialogadvtab](https://ckeditor.com/cke4/addon/dialogadvtab)                     | N/A                                                                                                                                                                                                                                   |
| [dialogui](https://ckeditor.com/cke4/addon/dialogui)                             | N/A                                                                                                                                                                                                                                   |
| [div](https://ckeditor.com/cke4/addon/div)                                       | Partially covered by [General HTML Support](https://ckeditor.com/docs/ckeditor5/latest/features/general-html-support.html)                                                                                                            |
| [divarea](https://ckeditor.com/cke4/addon/divarea)                               | Core ([Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html))                                                                                                                                                        |
| [docprops](https://ckeditor.com/cke4/addon/docprops)                             | N/A                                                                                                                                                                                                                                   |
| [easyimage](https://ckeditor.com/cke4/addon/easyimage)                           | [Easy Image](https://ckeditor.com/docs/ckeditor5/latest/features/images/image-upload/easy-image.html)                                                                                                                                 |
| [editorplaceholder](https://ckeditor.com/cke4/addon/editorplaceholder)           | [Editor placeholder](#ckeditor5/latest/features/editor-placeholder.html)                                                                                                                                                              |
| [elementspath](https://ckeditor.com/cke4/addon/elementspath)                     | N/A                                                                                                                                                                                                                                   |
| [embed](https://ckeditor.com/cke4/addon/embed)                                   | [Media embed](#ckeditor5/latest/features/media-embed.html)                                                                                                                                                                            |
| [embedbase](https://ckeditor.com/cke4/addon/embedbase)                           | [Media embed](#ckeditor5/latest/features/media-embed.html--media-providers) configuration                                                                                                                                             |
| [embedsemantic](https://ckeditor.com/cke4/addon/embedsemantic)                   | [Media embed](#ckeditor5/latest/features/media-embed.html--semantic-data-output-default) configuration                                                                                                                                |
| [emoji](https://ckeditor.com/cke4/addon/emoji)                                   | [Emoji](#ckeditor5/latest/features/emoji.html)                                                                                                                                                                                        |
| [enterkey](https://ckeditor.com/cke4/addon/enterkey)                             | [Enter](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fenter%5Fenter-Enter.html) (except for the ENTER\_DIV option)                                                                                                          |
| [entities](https://ckeditor.com/cke4/addon/entities)                             | N/A                                                                                                                                                                                                                                   |
| [fakeobjects](https://ckeditor.com/cke4/addon/fakeobjects)                       | [Custom widgets](https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/implementing-a-block-widget.html)                                                                                                                     |
| [filebrowser](https://ckeditor.com/cke4/addon/filebrowser)                       | See [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html)                                                                                                                                                  |
| [filetools](https://ckeditor.com/cke4/addon/filetools)                           | See [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html)                                                                                                                                                  |
| [find](https://ckeditor.com/cke4/addon/find)                                     | [Find and replace](#ckeditor5/latest/features/find-and-replace.html)                                                                                                                                                                  |
| [flash](https://ckeditor.com/cke4/addon/flash)                                   | N/A                                                                                                                                                                                                                                   |
| [floatingspace](https://ckeditor.com/cke4/addon/floatingspace)                   | [Inline editor](#ckeditor5/latest/getting-started/setup/editor-types.html--inline-editor)                                                                                                                                             |
| [floatpanel](https://ckeditor.com/cke4/addon/floatpanel)                         | Partially covered by the [createDropdown()](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fdropdown%5Futils.html#function-createDropdown) utility                                                                       |
| [font](https://ckeditor.com/cke4/addon/font)                                     | [Font size and Font family](#ckeditor5/latest/features/font.html)                                                                                                                                                                     |
| [format](https://ckeditor.com/cke4/addon/format)                                 | Partially covered by the [Heading](#ckeditor5/latest/features/headings.html) and [Paragraph](https://ckeditor.com/docs/ckeditor5/latest/api/paragraph.html) features                                                                  |
| [forms](https://ckeditor.com/cke4/addon/forms)                                   | N/A                                                                                                                                                                                                                                   |
| [horizontalrule](https://ckeditor.com/cke4/addon/horizontalrule)                 | [Horizontal line](#ckeditor5/latest/features/horizontal-line.html)                                                                                                                                                                    |
| [htmlwriter](https://ckeditor.com/cke4/addon/htmlwriter)                         | A custom HTML writer can be implemented using the [HtmlWriter](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fdataprocessor%5Fhtmlwriter-DataProcessorHtmlWriter.html) interface                                    |
| [iframe](https://ckeditor.com/cke4/addon/iframe)                                 | [HTML embed](#ckeditor5/latest/features/html/html-embed.html)                                                                                                                                                                         |
| [iframedialog](https://ckeditor.com/cke4/addon/iframedialog)                     | N/A                                                                                                                                                                                                                                   |
| [image](https://ckeditor.com/cke4/addon/image)                                   | [Image](#ckeditor5/latest/features/images/images-overview.html)                                                                                                                                                                       |
| [image2](https://ckeditor.com/cke4/addon/image2)                                 | [Image](#ckeditor5/latest/features/images/images-overview.html)                                                                                                                                                                       |
| [imagebase](https://ckeditor.com/cke4/addon/imagebase)                           | [Image](#ckeditor5/latest/features/images/images-overview.html)                                                                                                                                                                       |
| [indent](https://ckeditor.com/cke4/addon/indent)                                 | [Indent](#ckeditor5/latest/features/indent.html--indenting-lists)                                                                                                                                                                     |
| [indentblock](https://ckeditor.com/cke4/addon/indentblock)                       | Introduced by [IndentBlock](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Findent%5Findentblock-IndentBlock.html), exposed by [Indent](#ckeditor5/latest/features/indent.html)                                               |
| [indentlist](https://ckeditor.com/cke4/addon/indentlist)                         | Introduced by [ListEditing](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Flist%5Flist%5Flistediting-ListEditing.html), exposed by [Indent](#ckeditor5/latest/features/indent.html--indenting-lists)                         |
| [justify](https://ckeditor.com/cke4/addon/justify)                               | [Text alignment](#ckeditor5/latest/features/text-alignment.html)                                                                                                                                                                      |
| [language](https://ckeditor.com/cke4/addon/language)                             | [Text part language](#ckeditor5/latest/features/language.html)                                                                                                                                                                        |
| [lineutils](https://ckeditor.com/cke4/addon/lineutils)                           | Partially covered by [Widget type around](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fwidget%5Fwidgettypearound%5Fwidgettypearound-WidgetTypeAround.html)                                                                 |
| [link](https://ckeditor.com/cke4/addon/link)                                     | [Link](#ckeditor5/latest/features/link.html)                                                                                                                                                                                          |
| [list](https://ckeditor.com/cke4/addon/list)                                     | [List](#ckeditor5/latest/features/lists/lists.html)                                                                                                                                                                                   |
| [listblock](https://ckeditor.com/cke4/addon/listblock)                           | [Dropdowns](#ckeditor5/latest/framework/architecture/ui-library.html--dropdowns) and the [addListToDropdown()](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fdropdown%5Futils.html#function-addListToDropdown) utility |
| [liststyle](https://ckeditor.com/cke4/addon/liststyle)                           | [List properties](#ckeditor5/latest/features/lists/lists-properties.html)                                                                                                                                                             |
| [magicline](https://ckeditor.com/cke4/addon/magicline)                           | [Widget type around](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fwidget%5Fwidgettypearound-WidgetTypeAround.html)                                                                                                         |
| [mathjax](https://ckeditor.com/cke4/addon/mathjax)                               | [MathType](#ckeditor5/latest/features/math-equations.html)                                                                                                                                                                            |
| [maximize](https://ckeditor.com/cke4/addon/maximize)                             | [Fullscreen mode](#ckeditor5/latest/features/fullscreen.html)                                                                                                                                                                         |
| [mentions](https://ckeditor.com/cke4/addon/mentions)                             | [Mentions](#ckeditor5/latest/features/mentions.html)                                                                                                                                                                                  |
| [menu](https://ckeditor.com/cke4/addon/menu)                                     | [Dropdowns](#ckeditor5/latest/framework/architecture/ui-library.html--dropdowns)                                                                                                                                                      |
| [menubutton](https://ckeditor.com/cke4/addon/menubutton)                         | [Dropdowns](#ckeditor5/latest/framework/architecture/ui-library.html--dropdowns)                                                                                                                                                      |
| [newpage](https://ckeditor.com/cke4/addon/newpage)                               | N/A                                                                                                                                                                                                                                   |
| [notification](https://ckeditor.com/cke4/addon/notification)                     | [Notification](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fnotification%5Fnotification-Notification.html) (provides only the engine, without UI)                                                                     |
| [notificationaggregator](https://ckeditor.com/cke4/addon/notificationaggregator) | N/A                                                                                                                                                                                                                                   |
| [pagebreak](https://ckeditor.com/cke4/addon/pagebreak)                           | [Page break](#ckeditor5/latest/features/page-break.html)                                                                                                                                                                              |
| [panel](https://ckeditor.com/cke4/addon/panel)                                   | [UI library](#ckeditor5/latest/framework/architecture/ui-library.html)                                                                                                                                                                |
| [panelbutton](https://ckeditor.com/cke4/addon/panelbutton)                       | [UI library](#ckeditor5/latest/framework/architecture/ui-library.html)                                                                                                                                                                |
| [pastefromgdocs](https://ckeditor.com/cke4/addon/pastefromgdocs)                 | [Paste from Google Docs](#ckeditor5/latest/features/pasting/paste-from-google-docs.html)                                                                                                                                              |
| [pastefromlibreoffice](https://ckeditor.com/cke4/addon/pastefromlibreoffice)     | N/A                                                                                                                                                                                                                                   |
| [pastefromword](https://ckeditor.com/cke4/addon/pastefromword)                   | [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html)                                                                                                                                                        |
| [pastetext](https://ckeditor.com/cke4/addon/pastetext)                           | [Paste plain text](#ckeditor5/latest/features/pasting/paste-plain-text.html)                                                                                                                                                          |
| [pastetools](https://ckeditor.com/cke4/addon/pastetools)                         | N/A                                                                                                                                                                                                                                   |
| [placeholder](https://ckeditor.com/cke4/addon/placeholder)                       | [Custom implementation](https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/implementing-an-inline-widget.html)                                                                                                            |
| [popup](https://ckeditor.com/cke4/addon/popup)                                   | N/A                                                                                                                                                                                                                                   |
| [preview](https://ckeditor.com/cke4/addon/preview)                               | N/A                                                                                                                                                                                                                                   |
| [print](https://ckeditor.com/cke4/addon/print)                                   | N/A                                                                                                                                                                                                                                   |
| [removeformat](https://ckeditor.com/cke4/addon/removeformat)                     | [Remove format](#ckeditor5/latest/features/remove-format.html)                                                                                                                                                                        |
| [resize](https://ckeditor.com/cke4/addon/resize)                                 | N/A                                                                                                                                                                                                                                   |
| [richcombo](https://ckeditor.com/cke4/addon/richcombo)                           | [DropdownView](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fui%5Fdropdown%5Fdropdownview-DropdownView.html)                                                                                                                |
| [save](https://ckeditor.com/cke4/addon/save)                                     | See [Saving data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html)                                                                                                                                              |
| [selectall](https://ckeditor.com/cke4/addon/selectall)                           | [Select all](#ckeditor5/latest/features/select-all.html)                                                                                                                                                                              |
| [sharedspace](https://ckeditor.com/cke4/addon/sharedspace)                       | Custom implementation - see [multi-root editor](#ckeditor5/latest/examples/builds/multi-root-editor.html)                                                                                                                             |
| [showblocks](https://ckeditor.com/cke4/addon/showblocks)                         | [Show blocks](#ckeditor5/latest/features/show-blocks.html)                                                                                                                                                                            |
| [showborders](https://ckeditor.com/cke4/addon/showborders)                       | [Table properties](#ckeditor5/latest/features/tables/tables-styling.html)                                                                                                                                                             |
| [smiley](https://ckeditor.com/cke4/addon/smiley)                                 | [Emoji](#ckeditor5/latest/features/emoji.html)                                                                                                                                                                                        |
| [sourcearea](https://ckeditor.com/cke4/addon/sourcearea)                         | [Source code editing](#ckeditor5/latest/features/source-editing/source-editing.html)                                                                                                                                                  |
| [sourcedialog](https://ckeditor.com/cke4/addon/sourcedialog)                     | [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html)                                                                                                                                |
| [specialchar](https://ckeditor.com/cke4/addon/specialchar)                       | [Special characters](#ckeditor5/latest/features/special-characters.html)                                                                                                                                                              |
| [stylescombo](https://ckeditor.com/cke4/addon/stylescombo)                       | [Style](#ckeditor5/latest/features/style.html)                                                                                                                                                                                        |
| [stylesheetparser](https://ckeditor.com/cke4/addon/stylesheetparser)             | N/A                                                                                                                                                                                                                                   |
| [tab](https://ckeditor.com/cke4/addon/tab)                                       | See [Keyboard support](#ckeditor5/latest/features/accessibility.html)                                                                                                                                                                 |
| [table](https://ckeditor.com/cke4/addon/table)                                   | [Table](#ckeditor5/latest/features/tables/tables.html)                                                                                                                                                                                |
| [tableresize](https://ckeditor.com/cke4/addon/tableresize)                       | [Table column resize](#ckeditor5/latest/features/tables/tables-resize.html)                                                                                                                                                           |
| [tableselection](https://ckeditor.com/cke4/addon/tableselection)                 | [Table selection](#ckeditor5/latest/features/tables/tables.html--table-selection)                                                                                                                                                     |
| [tabletools](https://ckeditor.com/cke4/addon/tabletools)                         | [Table properties](#ckeditor5/latest/features/tables/tables-styling.html)                                                                                                                                                             |
| [templates](https://ckeditor.com/cke4/addon/templates)                           | [Template](#ckeditor5/latest/features/template.html)                                                                                                                                                                                  |
| [textmatch](https://ckeditor.com/cke4/addon/textmatch)                           | N/A                                                                                                                                                                                                                                   |
| [textwatcher](https://ckeditor.com/cke4/addon/textwatcher)                       | [Text watcher](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Ftyping%5Ftextwatcher-TextWatcher.html)                                                                                                                         |
| [toolbar](https://ckeditor.com/cke4/addon/toolbar)                               | [Editor toolbar](https://ckeditor.com/docs/ckeditor5/latest/features/toolbar/toolbar.html)                                                                                                                                            |
| [uicolor](https://ckeditor.com/cke4/addon/uicolor)                               | See [Theme customization](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html)                                                                                                                                          |
| [undo](https://ckeditor.com/cke4/addon/undo)                                     | [Undo](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fundo%5Fundo-Undo.html)                                                                                                                                                 |
| [uploadfile](https://ckeditor.com/cke4/addon/uploadfile)                         | See [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html)                                                                                                                                                  |
| [uploadimage](https://ckeditor.com/cke4/addon/uploadimage)                       | See [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html)                                                                                                                                                  |
| [uploadwidget](https://ckeditor.com/cke4/addon/uploadwidget)                     | See [image upload](#ckeditor5/latest/features/images/image-upload/image-upload.html)                                                                                                                                                  |
| [widget](https://ckeditor.com/cke4/addon/widget)                                 | [Widget](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fwidget%5Fwidget-Widget.html)                                                                                                                                         |
| [widgetselection](https://ckeditor.com/cke4/addon/widgetselection)               | [Widget](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fwidget%5Fwidget-Widget.html)                                                                                                                                         |
| [wysiwygarea](https://ckeditor.com/cke4/addon/wysiwygarea)                       | Core ([Classic editor](#ckeditor5/latest/examples/builds/classic-editor.html) \- there is no iframe-based editor implementation in CKEditor 5)                                                                                        |
| [xml](https://ckeditor.com/cke4/addon/xml)                                       | [XML data processor](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fdataprocessor%5Fxmldataprocessor-XmlDataProcessor.html)                                                                                         |

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html">source file: "ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html"</a>

## Troubleshooting migration from CKEditor 4

This article describes some issues that you may encounter when migrating from CKEditor 4 to CKEditor 5.

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html--why-does-the-editor-filter-out-my-content-styles-classes-elements-where-is-configallowedcontent-true">

### Why does the editor filter out my content (styles, classes, elements)? Where is `config.allowedContent = true`?

Unlike [CKEditor 4](https://ckeditor.com/ckeditor-4/), CKEditor 5 implements a custom [data model](#ckeditor5/latest/framework/architecture/editing-engine.html). This means that every piece of content that is loaded into the editor needs to be converted to that model and then rendered back to the view.

Each kind of content must be handled by a dedicated plugin. For instance, the [ckeditor5-basic-styles](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles) package handles HTML elements such as `<b>`, `<i>`, `<u>`, etc. along with their representation in the model. The feature defines the two–way conversion between the HTML (view) and the editor model.

If you load some content that is not recognizable to any of the editor features, it will be dropped. If you want all the HTML5 elements to be supported, you need to write plugins to support them. Once you do that and load these plugins into your editor instance, CKEditor 5 will no longer filter anything out.

You may also use the [General HTML support](#ckeditor5/latest/features/html/general-html-support.html) functionality to enable HTML features that are not explicitly supported by CKEditor 5 plugins.

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html--what-happened-to-the-contentscss-file-how-do-i-style-the-content-of-the-editor">

### What happened to the `contents.css` file? How do I style the content of the editor?

There is no such thing as the `contents.css` file anymore. This is because in CKEditor 5 the features bring their own content styles, [provided via CSS files](#ckeditor5/latest/getting-started/setup/css.html).

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html--where-are-the-editorinserthtml-and-editorinserttext-methods-how-to-insert-some-content">

### Where are the `editor.insertHtml()` and `editor.insertText()` methods? How to insert some content?

Refer to [this CKEditor 5 How-to question](#ckeditor5/latest/framework/how-tos.html--how-to-insert-some-content-into-the-editor).

<a id="ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html--what-happened-to-the-global-windowckeditor-how-to-list-all-instances-of-the-editor">

### What happened to the global `window.CKEDITOR`? How to list all instances of the editor?

Refer to [this CKEditor 5 How-to question](#ckeditor5/latest/framework/how-tos.html--how-to-list-all-instances-of-the-editor).

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html">source file: "ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html"</a>

## Migration from CKEditor 4

This section of the documentation explains how to migrate to CKEditor 5.

When compared to its predecessor, you should treat CKEditor 5 as **a totally new editor**. We have redesigned every single aspect of it – from installation, to integration, to features, to its data model, and finally to its API.

There is no automatic solution for migrating. This section summarizes the most important aspects you need to consider before you proceed with moving to CKEditor 5.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--differences-between-ckeditor-4-and-ckeditor-5">

### Differences between CKEditor 4 and CKEditor 5

What differentiates CKEditor 5 from its predecessor the most is its core architecture. CKEditor 5 is a highly flexible and extensible editing framework with a powerful API. You can use it to create any WYSIWYG editor implementation, from a lightweight chat to a complex Google Docs-like solution. CKEditor 5 is also collaboration-ready and offers features such as real-time collaboration, comments, or track changes.

Here are the key differences between the two editor versions:

|                                      | **CKEditor 4**                                                              | **CKEditor 5**                                                                           |
| ------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Programming language**             | JavaScript                                                                  | TypeScript                                                                               |
| **Data model**                       | HTML/DOM                                                                    | Custom data model and virtual DOM implementation                                         |
| **Architecture**                     | Plugin-based                                                                | Plugin-based, MVC                                                                        |
| **Editor types**                     | Classic, inline                                                             | Classic, inline, decoupled (document), balloon, balloon block, multi-root                |
| **Collaboration-ready**              | ❌                                                                           | ✅                                                                                        |
| **File management and image upload** | CKFinder                                                                    | CKBox, CKFinder                                                                          |
| **UI**                               | Toolbar, dialogs, and features manipulated through right-click context menu | Toolbar, dropdowns, balloons, and features manipulated through on-click feature toolbars |
| **UI customization**                 | Skins, UI color change                                                      | Themes, customization with CSS variables                                                 |
| **License**                          | GPL, MPL, LGPL, commercial license                                          | GPL 2+ or commercial license                                                             |

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--feature-comparison-of-ckeditor-4-and-ckeditor-5">

### Feature comparison of CKEditor 4 and CKEditor 5

Digital content editing paradigms have changed a lot between the times of CKEditor 4 and now. We designed and built CKEditor 5 from scratch, taking into account the possibilities of modern web apps, current web standards, and the needs of today’s users.

This new approach affects the [available feature set](#ckeditor5/latest/features/index.html), how features were implemented, and what configuration options are available for them. To make it easier to compare both editor versions, we have created the following compatibility tables:

* [CKEditor 4 plugin equivalents](#ckeditor5/latest/updating/ckeditor4/ckeditor4-plugin-compatibility.html)
* [CKEditor 4 configuration options compatibility](#ckeditor5/latest/updating/ckeditor4/ckeditor4-configuration-compatibility.html)

You can use them to check the CKEditor 5 equivalents of some features or configuration options from CKEditor 4\. If there is no direct equivalent, the tables will point you to a solution recommended in CKEditor 5\. We strongly advise you to treat the migration to CKEditor 5 as an opportunity to modernize your application and rethink your editing solutions.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--before-you-migrate">

### Before you migrate

CKEditor 4 and CKEditor 5 are two different products. Here are the most important aspects you need to consider before you migrate.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--migrating-existing-data">

#### Migrating existing data

Perform extensive analysis, data verification, and tests on existing data. If necessary, you will need to develop conversion procedures to avoid data loss. You can use the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) feature to introduce HTML markup that is present in the legacy content but is not yet fully covered by CKEditor 5 features.

If your legacy content includes `<script>` tags that worked in CKEditor 4, see the [Enabling script tags for legacy use cases](#ckeditor5/latest/features/html/general-html-support.html--enabling-script-tags-for-legacy-use-cases) section in the General HTML Support guide.

The [Plugins and HTML output](#ckeditor5/latest/framework/architecture/plugins.html--plugins-and-html-output) article lists all official CKEditor 5 plugins and the HTML output they produce. You can use it to check the compatibility of legacy data with what is supported in CKEditor 5.

A simple yet efficient strategy for adopting CKEditor 5 into existing systems might be using CKEditor 5 for creating new content and the old editor for editing legacy content.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--installation-and-integration">

#### Installation and integration

The first aspect that changed with CKEditor 5 is its installation procedure. It became much more modern with the introduction of modular patterns, UMD, npm, etc. Refer to the [Getting started](#ckeditor5/latest/getting-started/index.html) section to explore all available installation and integration options.

The API for integrating CKEditor with your pages changed, too. Check the [Editor lifecycle](#ckeditor5/latest/getting-started/setup/editor-lifecycle.html) and [Getting and setting data](#ckeditor5/latest/getting-started/setup/getting-and-setting-data.html) articles for an introduction to this topic.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--custom-plugins">

#### Custom plugins

Any custom plugins you have developed for CKEditor 4 will not be compatible with CKEditor 5\. Although their idea may stay the same, their implementation will certainly be different and will require rewriting them from scratch.

The same may apply to third-party plugins. They may not have been ported to CKEditor 5 yet.

Check the [Creating plugins](#ckeditor5/latest/framework/architecture/plugins.html--creating-plugins) section for more information on the development of plugins.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--custom-themes-skins">

#### Custom themes (skins)

In CKEditor 5, the earlier concept of “skins” was reviewed and is now called “themes.”

If you have custom skins for CKEditor 4, you need to re-create them for CKEditor 5\. Fortunately, custom theming in CKEditor 5 is much more powerful and simpler than before.

What’s new: you can use CKEditor 5 as a [headless editor integrated with an external UI](#ckeditor5/latest/framework/deep-dive/ui/external-ui.html), for example, created in React. Many projects use the powerful editing engine of CKEditor 5 coupled with a custom UI for seamless integration with their application.

For more information, check how to [customize the themes](#ckeditor5/latest/framework/deep-dive/ui/theme-customization.html) in the CKEditor 5 Framework documentation.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--image-upload">

#### Image upload

CKEditor 5 supports several different image upload strategies. Check out the [comprehensive “Image upload” guide](#ckeditor5/latest/features/images/image-upload/image-upload.html) to find out the best option for your project.

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--license">

#### License

CKEditor 4 was licensed under GPL, LGPL, and MPL Open Source licenses.

CKEditor 5 is licensed under GPL2+ Open Source license only. If you are running an Open Source project under an OSI-approved license incompatible with GPL, we will be happy to [support you with a no-cost license](https://ckeditor.com/contact/). If your project is a commercial one, you will need to [get a commercial license](https://ckeditor.com/contact/).

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--recommended-migration-strategy">

### Recommended migration strategy

You can approach moving from CKEditor 4 to CKEditor 5 as follows:

1. **Back up all your data.**
2. Learn about CKEditor 5\. Check the [demos](https://ckeditor.com/ckeditor-5/demo/), read about its [architecture](#ckeditor5/latest/framework/architecture/intro.html), and review the [available features](#ckeditor5/latest/features/index.html) and [integration methods](#ckeditor5/latest/getting-started/index.html).
3. Create a custom preset containing all the plugins you need the [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs).
4. Test loading pre-existing content created in CKEditor 4 into CKEditor 5\. Adjust the editor configuration and plugin set. If needed, enable the missing elements, classes, or attributes via the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) feature.
5. When you are sure no data loss will occur, you can focus on customizing your CKEditor 5 preset even more by changing the integration method, creating custom plugins, adjusting the theme, and enabling new features.

CKEditor 5 is a great, modern editing framework so migrating is a fantastic opportunity to level your content editing experience up. [Collaboration](#ckeditor5/latest/features/collaboration/collaboration.html) with real-time collaborative editing, comments and track changes, [revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html), [autoformatting](#ckeditor5/latest/features/autoformat.html), [import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html), export to [PDF](#ckeditor5/latest/features/converters/export-pdf.html) and [Word](#ckeditor5/latest/features/converters/export-word.html), [word and character count](#ckeditor5/latest/features/word-count.html), and [CKBox](#ckeditor5/latest/features/file-management/ckbox.html) file manager are just a few examples of new features that were not available in CKEditor 4\. Try them out!

<a id="ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html--support">

### Support

If you are missing any particular features or settings, feel free to [report an issue](#ckeditor5/latest/support/index.html--reporting-issues). Search the [issues section in the repository](https://github.com/ckeditor/ckeditor5/issues) first. The feature you are after may have already been reported – you can support it by upvoting the issue with 👍. Be as precise as possible, explaining the exact use case, the context where you use the editor, and the expected behavior.

The [Troubleshooting migration from CKEditor 4](#ckeditor5/latest/updating/ckeditor4/ckeditor4-troubleshooting.html) article answers some frequently asked questions about the migration.

[Contact the support team](https://ckeditor.com/contact/) if you want to learn more about licensing or the [Extended Support Model](https://ckeditor.com/ckeditor-4-support/).

<a id="ckeditor5/latest/updating/guides/changelog.html">source file: "ckeditor5/latest/updating/guides/changelog.html"</a>

## CKEditor 5 changelog

This is the CKEditor 5 changelog guide. Here you will find information about the most important changes introduced in the release, new features, and bug fixes.

Information about both major and minor breaking changes is available, too, if the release introduces them. You can read more about breaking changes in CKEditor 5 in the [Versioning policy](https://ckeditor.com/docs/ckeditor5/latest/support/versioning-policy.html#major-and-minor-breaking-changes) guide.

You can find more information about each release in the blog posts linked at the start of each entry.

This guide provides the changelog information for the 3 latest releases of CKEditor 5\. For older releases, refer to the [release notes on GitHub](https://github.com/ckeditor/ckeditor5/releases).

<a id="ckeditor5/latest/updating/guides/changelog.html--ckeditor-5-v4800-release">

### CKEditor 5 v48.0.0 release

We are happy to announce the release of CKEditor 5 v48.0.0.

<a id="ckeditor5/latest/updating/guides/changelog.html--release-highlights">

#### Release highlights

This major release improves CKEditor AI and tables, completes the sunset of old installation methods, changes the default `Export to PDF` converter API version, and introduces a unified structure for root-related configuration.

<a id="ckeditor5/latest/updating/guides/changelog.html--old-installation-methods-sunset">

##### Old installation methods sunset

With this release, we have officially completed the transition to our modern installation methods — a milestone we are excited to reach! 🎉

First [introduced in CKEditor 5 v42.0.0 in June 2024](https://ckeditor.com/blog/ckeditor-42-0-0-release-highlights/), these new methods were designed to simplify the developer workflow, reduce configuration overhead, and unlock faster, more consistent updates. With the old methods now fully retired, we can focus all our energy on delivering new features, improving performance, and moving the platform forward.

If your project still relies on old installation methods, migrate to the [new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html) to continue updating to this and later versions of CKEditor 5.

If migrating in the near term is not feasible, you can extend support for legacy installation methods with [CKEditor 5 Long Term Support (LTS)](https://ckeditor.com/ckeditor-5-lts/).

<a id="ckeditor5/latest/updating/guides/changelog.html--ckeditor-ai-improvements">

##### ⭐ CKEditor AI improvements

The styling of suggestion previews in [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html), [AI Review](#ckeditor5/latest/features/ai/ckeditor-ai-review.html), [AI Quick Actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html), and [AI Translate](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html) now more closely matches the content in the editing area, providing a more consistent visual experience. Initialization has also been optimized by caching model requests, reducing redundant network calls.

Colors used across the AI package are now available through a shared CSS variable palette, making AI components easier to customize. A new [programmatic API guide](#ckeditor5/latest/features/ai/ckeditor-ai-programmatic.html) also describes how to interact with AI features from code.

<a id="ckeditor5/latest/updating/guides/changelog.html--table-improvements">

##### Table improvements

We are introducing table alignment, giving users and integrators much more control over how tables are positioned relative to surrounding content. Tables can now be aligned left, or right with proper text wrapping — a feature well-known from CKEditor 4 that many users have been requesting.

[Table alignment](#ckeditor5/latest/features/tables/tables.html--table-alignment) now uses CSS margin-based positioning by default, producing cleaner output. With a configuration option, teams which are migrating from CKEditor 4 can switch the output back to inlinse styles if needed.

We are also introducing the [ability to switch table cell types](#ckeditor5/latest/features/tables/tables.html--table-cell-type) between header (`<th>`) and data (`<td>`) in the Cell Properties panel.

Additionally header cells can be associated with related row or column with the [scope attribute](#ckeditor5/latest/features/tables/tables.html--table-cell-scope) using the “Row header” or “Column header” options. These options help screen readers understand the table structure.

The editor now recognizes legacy HTML table attributes during upcasting, preserving styling from older HTML content and improving compatibility with CKEditor 4.

* The `<table border="N">` attribute is now converted to `tableBorderWidth`.
* The `<table cellpadding="N">` attribute is now converted to `tableCellPadding`.

Several default table behaviors have also been updated:

* Conversion of `border="0"` to borderless tables is now enabled by default.
* Table alignment is now output as CSS classes by default. Using inline styles is still possible with the `useInlineStyles` option.
* Support for the `scope` attribute in table header cells is now enabled by default.
* Added support for table footers, thanks to a community contribution from [@star-szr](https://github.com/star-szr).

<a id="ckeditor5/latest/updating/guides/changelog.html--export-to-pdf-default-version-change">

##### Export to PDF default version change

The Export to PDF feature now defaults to version 2 of the converter API, so you will enjoy a range of [powerful enhancements](#ckeditor5/latest/features/converters/export-pdf.html--html-to-pdf-converter-features) right out of the box — including advanced header and footer configurations, flexible page sizing, PDF metadata editing, owner password protection, and digital signature support.

Since the new version may produce slightly different output than version 1, we recommend reviewing the new [default configuration](#ckeditor5/latest/features/converters/export-pdf.html--default-configuration).

If you need to keep the previous behavior, simply set the `version` property in the `exportPdf` configuration object. See the [feature documentation](#ckeditor5/latest/features/converters/export-pdf.html--configuration) for full details on both API versions.

<a id="ckeditor5/latest/updating/guides/changelog.html--unified-root-configuration-structure">

##### Unified root configuration structure

Editor configuration options related to roots, such as `initialData`, `placeholder`, and `label`, are now grouped under `config.root` for single-root editors and `config.roots` for multi-root editors. This provides a more consistent structure for configuring editor roots.

The previous top-level configuration options remain functional but are now deprecated. See the [update guide](#ckeditor5/latest/updating/guides/update-to-48.html--root-configuration-migration-and-deprecated-top-level-options) for migration details.

Please refer to the [update guide](#ckeditor5/latest/updating/guides/update-to-48.html) to learn more about these changes.

<a id="ckeditor5/latest/updating/guides/changelog.html--major-breaking-changes">

#### MAJOR BREAKING CHANGES

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai), [uploadcare](https://www.npmjs.com/package/@ckeditor/ckeditor5-uploadcare)**: Simplified AI and Uploadcare configuration structures by replacing enums with plain string values. Refer to the official updating guide for [AI](#ckeditor5/latest/updating/guides/update-to-48.html--use-of-string-values-instead-of-enums) and [Uploadcare](#ckeditor5/latest/updating/guides/update-to-48.html--removal-of-enum-as-uploadcare-source-type).
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Renamed the `check` property to `commandId` in the `ai.chat.shortcuts` configuration. Refer to the [official updating guide](#ckeditor5/latest/updating/guides/update-to-48.html--ai-chat-shortcuts).
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Introduced the `label` property in place of `displayedPrompt` in the `ai.quickActions.extraCommands` configuration. The `displayedPrompt` property is now required only for extra commands with type `'chat'`. Refer to the [official updating guide](#ckeditor5/latest/updating/guides/update-to-48.html--ai-quick-actions).
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Changed the `type` property values in the `ai.quickActions.extraCommands` configuration from uppercase to lowercase. Refer to the [official updating guide](#ckeditor5/latest/updating/guides/update-to-48.html--ai-quick-actions).
* **[editor-multi-root](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-multi-root)**: The `config.rootsAttributes` and `config.lazyRoots` multi-root editor config options have been removed. See [#19885](https://github.com/ckeditor/ckeditor5/issues/19885).  
The `config.roots` option should be used instead to define the editor roots and their attributes.  
The `config.roots.<rootName>.modelAttributes` property should be used to define the attributes of a root, while  
the `config.roots.<rootName>.lazyLoad` property should be used to define whether a root should be lazy loaded or not.  
Note that `config.roots.<rootName>.lazyLoad` property is now deprecated and will be removed in the future.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Table alignment is now output as CSS classes instead of inline styles by default. See [#3225](https://github.com/ckeditor/ckeditor5/issues/3225).  
It can be reverted to the previous behaviour by setting the `useInlineStyles` configuration option to `true`.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Changed the default value of `table.tableLayout.stripFigureFromContentTable` from `true` to `false`. See [#19771](https://github.com/ckeditor/ckeditor5/issues/19771).  
As a result, the `<figure>` wrapper is now preserved on content tables by default when the layout tables feature is enabled.
* CKEditor 5 DLL builds are no longer available due to the deprecation of legacy installation methods. See the [migration path](#ckeditor5/latest/updating/nim-migration/dll-builds.html). See [#17779](https://github.com/ckeditor/ckeditor5/issues/17779).
* CKEditor 5 packages no longer ship the `src/`, `theme/` and `lang/` directories on npm due to the deprecation of legacy installation methods. See the [migration path](#ckeditor5/latest/updating/nim-migration/customized-builds.html). See [#17779](https://github.com/ckeditor/ckeditor5/issues/17779).
* All styles previously shipped in `@ckeditor/ckeditor5-theme-lark` have been redistributed to the appropriate packages, which now provide those CSS assets directly.

<a id="ckeditor5/latest/updating/guides/changelog.html--minor-breaking-changes">

#### MINOR BREAKING CHANGES

* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core), [editor-balloon](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-balloon), [editor-classic](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-classic), [editor-decoupled](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-decoupled), [editor-inline](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-inline), [editor-multi-root](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-multi-root)**: The editor no longer updates `config.initialData` during startup. Use `config.roots.main.initialData` for single-root editors and `config.roots.<rootName>.initialData` for multi-root editors. See [#19885](https://github.com/ckeditor/ckeditor5/issues/19885).
* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core), [editor-balloon](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-balloon), [editor-classic](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-classic), [editor-decoupled](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-decoupled), [editor-inline](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-inline), [editor-multi-root](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-multi-root), [watchdog](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog)**: Added support for creating editors and watchdogs using configuration only, without passing a source element or initial data as the first argument. Passing a source element or initial data as the first argument is now deprecated but still supported. Use `config.attachTo` for `ClassicEditor`, `config.root.element` for single-root editors, and `config.roots.<rootName>.element` for `MultiRootEditor`. See [#19887](https://github.com/ckeditor/ckeditor5/issues/19887).
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Moved the public API from `AIChat` to `AIChatController`. This affects integrations that use the `AIChat` API.
* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core)**: The default word breaking behavior in the content area has been updated to prevent unwanted breaks in tables. If you customized the `--ck-content-word-break` CSS variable in your integration, migrate to the new `--ck-content-overflow-wrap` variable to retain the same effect. See [#19986](https://github.com/ckeditor/ckeditor5/issues/19986).
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Deep schema verification during `model.insertContent()` is now enabled by default. It is no longer behind an experimental flag. See [#19217](https://github.com/ckeditor/ckeditor5/issues/19217).  
Previously, this behavior required opting in via `config.experimentalFlags.modelInsertContentDeepSchemaVerification: true`. Now it is always active, ensuring that all elements and attributes in inserted content follow the schema - including deeply nested structures.  
If needed, you can temporarily opt out by setting `config.experimentalFlags.modelInsertContentDeepSchemaVerification: false`. Note that this option is **deprecated** and will be removed in a future release.
* **[export-pdf](https://www.npmjs.com/package/@ckeditor/ckeditor5-export-pdf)**: `Export to PDF` now uses version `2` of the converter API by default. This may produce slightly different output, so update any converter options to match the new API. To keep version `1`, set the `version` property in the `exportPdf` configuration object.
* **[import-word](https://www.npmjs.com/package/@ckeditor/ckeditor5-import-word)**: The `ImportWordEditing#getToken()` method is now asynchronous and returns a promise.
* **[mention](https://www.npmjs.com/package/@ckeditor/ckeditor5-mention)**: Mention elements in the data output now include the `data-mention-uid` attribute. This affects only integrations that define custom mention downcast converters. If you defined one, update it to include `data-mention-uid` in the output and omit it during clipboard operations; see the [update guide](#ckeditor5/latest/updating/guides/update-to-48.html--mention-feature-now-persists-uid-as-data-mention-uid-in-the-data-output).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: The improved handling of table heading rows is now enabled by default. Rows are no longer incorrectly marked or moved as header rows when earlier rows are not header rows. See [#19431](https://github.com/ckeditor/ckeditor5/issues/19431).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Added new block-level left and right alignment options. The editor also recognizes equivalent inline margin styles and converts them to these alignment types. See [#3225](https://github.com/ckeditor/ckeditor5/issues/3225).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: The `shallow` option used with `TableUtils#setHeadingRows` and `TableUtils#setHeadingColumns` has been renamed to `updateCellType`. See [#19431](https://github.com/ckeditor/ckeditor5/issues/19431).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Added support for importing HTML tables with the legacy `border="0"` attribute as borderless tables. Closes [#19038](https://github.com/ckeditor/ckeditor5/issues/19038).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: The experimental handling of the legacy `border="0"` HTML attribute is now enabled by default. If you had `config.experimentalFlags.upcastTableBorderZeroAttributes` in your configuration, remove it because the flag is no longer recognized. See [#19038](https://github.com/ckeditor/ckeditor5/issues/19038).
* **[track-changes](https://www.npmjs.com/package/@ckeditor/ckeditor5-track-changes)**: Moved `TrackChangesEditing#registerBlockAttribute()` and `TrackChangesEditing#registerInlineAttribute()` to the `SuggestionConversion` plugin in the `ckeditor5-collaboration-core` package.  
The purpose and behavior of these methods remains the same.
* **[track-changes](https://www.npmjs.com/package/@ckeditor/ckeditor5-track-changes)**: Suggestion marker DOM elements now use the `data-suggestion` attribute consistently.  
This may affect custom code or CSS that relies on `data-suggestion-id`.
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: The scope of the `.ck-reset_all-excluded` class has been expanded to also include the container wearing that class (e.g. to limit inheritance of font properties).  
Because of this, elements of the CKEditor user interface excluded from the CSS reset by the usage of the `.ck-reset_all-excluded` class may be prone to unexpected styling. Please make sure to verify the visual styling of such UI elements after updating to this version.
* Updated to TypeScript `5.5.4`.

<a id="ckeditor5/latest/updating/guides/changelog.html--features">

#### Features

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: `AIChatController` plugin now fires `replyCreated` and `interactionCreated` events when a new `AIReply` or `AIChatInteraction` is created.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Added the `ai.chat.context.alwaysAddSelection` configuration option. When enabled, the document selection is added to the AI Chat context automatically. This option is disabled by default.
* **[export-pdf](https://www.npmjs.com/package/@ckeditor/ckeditor5-export-pdf)**: `Export to PDF` now uses version `2` of the converter API by default. To keep version `1`, set the `version` property in the `exportPdf` configuration object.
* **[footnotes](https://www.npmjs.com/package/@ckeditor/ckeditor5-footnotes)**: Added support for configuring the items available in the footnotes list styles dropdown. Pass the `listStyles` array in the configuration to choose which list styles are shown.
* **[footnotes](https://www.npmjs.com/package/@ckeditor/ckeditor5-footnotes)**: Added support for the `arabic-indic` list style in footnotes. It is not shown in the dropdown by default, but it can be added to the list of available styles using the `listStyles` configuration option.
* **[remove-format](https://www.npmjs.com/package/@ckeditor/ckeditor5-remove-format)**: The remove format feature now clears inherited formatting from empty paragraphs and other block elements. Closes [#19851](https://github.com/ckeditor/ckeditor5/issues/19851).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Introduced support for changing table cell types between `data` and `header`. Closes [#16730](https://github.com/ckeditor/ckeditor5/issues/16730).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Introduced support for the `scope` attribute in table header cells to improve semantic markup and screen reader accessibility. This feature is enabled by default and can be disabled by setting `config.table.tableCellProperties.scopedHeaders` to `false`. Closes [#3175](https://github.com/ckeditor/ckeditor5/issues/3175).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Added support for table footers. You can now specify the number of footer rows in a table. The table row context menu has been updated with a new `Footer row` toggle to control this setting. Closes [#12952](https://github.com/ckeditor/ckeditor5/issues/12952).  
This feature is disabled by default and can be enabled by setting `config.table.enableFooters` to `true`.  
Thanks to [@star-szr](https://github.com/star-szr).
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Preserved table borders from legacy HTML content. Closes [#19633](https://github.com/ckeditor/ckeditor5/issues/19633).  
When loading HTML content that uses the deprecated `border` attribute on tables, the editor now keeps the original border width instead of ignoring it.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Preserved table cell padding from legacy HTML content. Closes [#19634](https://github.com/ckeditor/ckeditor5/issues/19634).  
When loading HTML content that uses the deprecated `cellpadding` attribute on tables, the editor now keeps the original cell padding instead of ignoring it.

<a id="ckeditor5/latest/updating/guides/changelog.html--bug-fixes">

#### Bug fixes

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Fixed an issue where new lines were ignored in the user message displayed in the AI Chat feed.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Reset the “Show changes” button state after the balloon for an AI Quick Action is displayed.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Fixed the incorrect order of user messages and AI agent responses in the AI Chat feed when loading a conversation from history.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Fixed an error thrown when the user stopped an ongoing AI Chat interaction and the remaining replies were not flushed to the UI.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Fixed a console error that could occur when AI Quick Actions were closed during response streaming.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Fixed an error thrown by CKEditor AI features when processing content that contains mentions. See [#20010](https://github.com/ckeditor/ckeditor5/issues/20010).
* **[comments](https://www.npmjs.com/package/@ckeditor/ckeditor5-comments)**: Fixed inline annotations so they stay attached to the target element when it scrolls inside its parent container.
* **[code-block](https://www.npmjs.com/package/@ckeditor/ckeditor5-code-block)**: Fixed inconsistent vertical spacing around code blocks in the content area. Code blocks now use explicit vertical margins that match other block widgets. Closes [#19982](https://github.com/ckeditor/ckeditor5/issues/19982).
* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core)**: Fixed excessive word breaking in tables rendered in the content area. Words will now only break when they genuinely overflow their container, preventing awkward splits in narrow table columns. Closes [#19986](https://github.com/ckeditor/ckeditor5/issues/19986).
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Removed the unintended public exports `autoParagraphEmptyRoots`, `isParagraphable`, and `wrapInParagraph`.  
These utilities were not part of the supported public API.
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Gradients in background styles are no longer ignored and are properly normalized. Closes [#19787](https://github.com/ckeditor/ckeditor5/issues/19787).
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Fixed background normalization so it no longer drops layers from the `background` CSS shorthand. Multi-layer backgrounds are now parsed and serialized correctly. See [#19787](https://github.com/ckeditor/ckeditor5/issues/19787).
* **[footnotes](https://www.npmjs.com/package/@ckeditor/ckeditor5-footnotes)**: Fixed the footnotes configuration typings to use `defaultListStyle` instead of `defaultStyle`.
* **[import-word](https://www.npmjs.com/package/@ckeditor/ckeditor5-import-word)**: Improved the initialization time of the `ImportWordEditing` plugin. Token retrieval now runs in the background, so it does not block editor startup.
* **[link](https://www.npmjs.com/package/@ckeditor/ckeditor5-link)**: Removed the unintended public export `ensureSafeUrl`.  
This utility was not part of the supported public API.
* **[real-time-collaboration](https://www.npmjs.com/package/@ckeditor/ckeditor5-real-time-collaboration)**: Fixed the inconsistent font family in collaboration user markers.
* **[show-blocks](https://www.npmjs.com/package/@ckeditor/ckeditor5-show-blocks)**: Fixed the `Show blocks` feature so block labels render in all editor types when the `dir` attribute is present either on the editable element itself or on its ancestor wrapper. Closes [#19866](https://github.com/ckeditor/ckeditor5/issues/19866).
* **[track-changes](https://www.npmjs.com/package/@ckeditor/ckeditor5-track-changes)**: Fixed suggestion marker DOM elements that used `data-suggestion-id` instead of `data-suggestion`.
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: Updated the CSS reset rules so `.ck-reset_all-excluded` also applies to the container that uses this class. Closes [#19967](https://github.com/ckeditor/ckeditor5/issues/19967).  
This change reduces the impact of the CKEditor’s `.ck-reset_all` class in DOM elements that are explicitly excluded from the reset by the `.ck-reset_all-excluded` class.
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: Disabling a menu bar menu now also closes it if it was open, preventing an open panel from remaining in a non-interactive state. Closes [#18214](https://github.com/ckeditor/ckeditor5/issues/18214).

<a id="ckeditor5/latest/updating/guides/changelog.html--other-changes">

#### Other changes

* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core), [editor-balloon](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-balloon), [editor-classic](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-classic), [editor-decoupled](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-decoupled), [editor-inline](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-inline), [editor-multi-root](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-multi-root), [watchdog](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog)**: Reorganized root-related editor configuration under `config.root` for single-root editors and `config.roots` for multi-root editors. Closes [#19885](https://github.com/ckeditor/ckeditor5/issues/19885).  
The `config.initialData`, `config.placeholder`, and `config.label` options are deprecated in favor of `config.root.initialData`, `config.root.placeholder`, and `config.root.label`.  
In multi-root editors, define these options per root using `config.roots.<rootName>.initialData`, `config.roots.<rootName>.placeholder`, and `config.roots.<rootName>.label`.
* **[paste-from-office](https://www.npmjs.com/package/@ckeditor/ckeditor5-paste-from-office), [table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Introduced new table block alignments, `blockLeft` and `blockRight`, allowing tables to be aligned to the left or right without text wrapping. The table properties balloon now includes two new buttons to easily apply these alignments. Closes [#3225](https://github.com/ckeditor/ckeditor5/issues/3225), [#6174](https://github.com/ckeditor/ckeditor5/issues/6174), [#8412](https://github.com/ckeditor/ckeditor5/issues/8412), [#8752](https://github.com/ckeditor/ckeditor5/issues/8752), [#9982](https://github.com/ckeditor/ckeditor5/issues/9982), [#10867](https://github.com/ckeditor/ckeditor5/issues/10867), [#14921](https://github.com/ckeditor/ckeditor5/issues/14921), [#17932](https://github.com/ckeditor/ckeditor5/issues/17932), [#19337](https://github.com/ckeditor/ckeditor5/issues/19337).  
Added additional spacing between a table and the surrounding text when wrapping is enabled. This prevents issues such as list markers overlapping with the table when placed next to each other.  
Added support for pasting to and from MS Word for all table alignment types: `left`, `right`, `center`, `blockLeft`, and `blockRight`.
* **[collaboration-core](https://www.npmjs.com/package/@ckeditor/ckeditor5-collaboration-core), [track-changes](https://www.npmjs.com/package/@ckeditor/ckeditor5-track-changes)**: Moved `TrackChangesEditing#registerBlockAttribute()` and `TrackChangesEditing#registerInlineAttribute()` to the `SuggestionConversion` plugin in the `ckeditor5-collaboration-core` package.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: `AIChatController` is now a public class. Moved public API from `AIChat` to `AIChatController` to avoid duplication.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Decreased the line height in the AI Chat prompt input field to match feed messages.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: `AIChat#addSelectionToChatContext()` now returns `void` instead of `Promise`.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Suggestion previews in AI features now follow the styling of the content in the editing area more closely.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Optimized AI features initialization by caching model requests, reducing redundant network calls and improving load performance.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Improved handling of agent responses in the Markdown format.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Marked selected AI programmatic APIs as experimental. These APIs are production-ready but may change in minor releases without the standard deprecation policy.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Added a shared CSS variable palette for colors used across the `ckeditor5-ai` package.  
This makes AI components easier to customize.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Removed the built-in Amazon Bedrock integration in the legacy AI Assistant. The `AWSTextAdapter` class remains available but now throws an error when used, and this change does not affect CKEditor AI. If you rely on this integration, contact [support](https://support.ckeditor.com).
* **[ckbox](https://www.npmjs.com/package/@ckeditor/ckeditor5-ckbox)**: Fixed an issue where the CKBox dialog was not visible in fullscreen mode. Closes [#19290](https://github.com/ckeditor/ckeditor5/issues/19290).
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: `Model#hasContent()` can now check `ModelSelection` and `ModelDocumentSelection` instances. See [#19847](https://github.com/ckeditor/ckeditor5/issues/19847).
* **[markdown-gfm](https://www.npmjs.com/package/@ckeditor/ckeditor5-markdown-gfm)**: Enhanced `MarkdownGfmMdToHtml` to support custom plugins and to export the default plugin chain used by the Markdown parser.
* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: Introduced `Rect.getDomElementRects()` method that conveniently retrieves all `Rects` of a DOM element while preserving their source for further processing (e.g. `Rect#getVisible()`).
* Replaced string-based soft requirements with plugin constructors across selected packages to improve developer experience and align plugin dependency handling across repositories. This update also adjusts package metadata and dependencies to match the new constructor-based requirements. See [#17779](https://github.com/ckeditor/ckeditor5/issues/17779). Closes [#19747](https://github.com/ckeditor/ckeditor5/issues/19747).  
The following dependencies no longer rely on soft requirements:

  * `ckeditor5-ai`: `CloudServices`.
  * `ckeditor5-ckbox`: `LinkEditing`, `PictureEditing`, `ImageUtils`, `ImageEditing`, `ImageUploadEditing`, `ImageUploadProgress`, `CloudServices`.
  * `ckeditor5-ckfinder`: `Link`, `LinkEditing`, `CKFinderUploadAdapter`.
  * `ckeditor5-easy-image`: `CloudServices`, `ImageUpload`.
  * `ckeditor5-emoji`: `Mention`.
  * `ckeditor5-export-pdf`: `CloudServices`.
  * `ckeditor5-export-word`: `CloudServices`.
  * `ckeditor5-heading`: `Paragraph`.
  * `ckeditor5-import-word`: `CloudServices`.
  * `ckeditor5-link`: `ImageEditing`, `ImageUtils`, `ImageBlockEditing`.
  * `ckeditor5-list-multi-level`: `ListEditing`.
  * `ckeditor5-merge-fields`: `ImageUtils`, `ImageEditing`, `Mention`.
  * `ckeditor5-paste-from-office-enhanced`: `PasteFromOffice`.
  * `ckeditor5-real-time-collaboration`: `Comments`, `CommentsRepository`, `CloudServices`, `RevisionHistory`, `TrackChanges`, `TrackChangesEditing`.
  * `ckeditor5-revision-history`: `Users`.
  * `ckeditor5-slash-command`: `Mention`.
  * `ckeditor5-style`: `GeneralHtmlSupport`.
  * `ckeditor5-track-changes`: `Comments`, `CommentsRepository`, `Annotations`, `EditorAnnotations`.
  * `ckeditor5-typing`: `Delete`, `Input`.
  * `ckeditor5-uploadcare`: `PictureEditing`, `ImageUploadEditing`, `ImageUploadProgress`, `ImageEditing`, `ImageUtils`.
* Updated `es-toolkit` to `v1.45.1`.
* Updated translations.

<a id="ckeditor5/latest/updating/guides/changelog.html--ckeditor-5-v4762-release">

### CKEditor 5 v47.6.2 release

We are releasing CKEditor 5 v47.6.2, a patch for the v47 line that removes the no-longer-functional Amazon Bedrock AI integration in the legacy AI Assistant plugin.

<a id="ckeditor5/latest/updating/guides/changelog.html--other-changes-2">

#### Other changes

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Removed the built-in Amazon Bedrock integration in the legacy AI Assistant. The `AWSTextAdapter` class remains available but now throws an error when used, and this change does not affect CKEditor AI. If you rely on this integration, contact [support](https://support.ckeditor.com).

<a id="ckeditor5/latest/updating/guides/changelog.html--ckeditor-5-v4761-release">

### CKEditor 5 v47.6.1 release

We are releasing CKEditor 5 v47.6.1, a patch that fixed three regressions discovered after v47.6.0.

<a id="ckeditor5/latest/updating/guides/changelog.html--bug-fixes-2">

#### Bug fixes

* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine), [undo](https://www.npmjs.com/package/@ckeditor/ckeditor5-undo)**: Fixed undo marker restoration for markers spanning multiple paragraphs. Previously, comments and suggestions could be restored to incorrect ranges. Closes [#19916](https://github.com/ckeditor/ckeditor5/issues/19916).
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Resolved an issue where AI Chat would crash when attempting to open a past conversation that was created by a model no longer available.
* **[widget](https://www.npmjs.com/package/@ckeditor/ckeditor5-widget)**: Fixed a regression where the caret (`|`) jumped over an empty paragraph when navigating with arrow keys near widgets. Closes [#19812](https://github.com/ckeditor/ckeditor5/issues/19812).

<a id="ckeditor5/latest/updating/guides/update-to-42.html">source file: "ckeditor5/latest/updating/guides/update-to-42.html"</a>

## Update to CKEditor 5 v42.x

<a id="ckeditor5/latest/updating/guides/update-to-42.html--update-to-ckeditor-5-v4200">

### Update to CKEditor 5 v42.0.0

Released on June 26, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v42.0.0))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v42.0.0.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--new-installation-methods">

#### New installation methods

This release introduces new installation methods. We simplified dependency management, made CKEditor 5 bundler-agnostic, and improved the startup performance through separate CSS distribution.

The most prominent changes:

* All plugins and core features are now available from the unified [ckeditor5](https://www.npmjs.com/package/ckeditor5) and [ckeditor5-premium-features](https://www.npmjs.com/package/ckeditor5-premium-features) packages, reducing dependency management complexity.
* Our packages became bundler-agnostic. You can use whatever bundler you want (such as Vite or esbuild) to integrate CKEditor 5.
* CSS files are now distributed separately from JavaScript, allowing for parallel downloading, easier customization, and improved performance.
* All the new distribution methods (available via npm, CDN, and ZIP downloads) allow dynamic plugin registration making it easy to add or remove plugins dynamically.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--migration-paths">

##### Migration paths

The old installation methods are still supported, but we put them on the deprecation path. Detailed [migration guides](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html) can be found in our documentation. These guides provide step-by-step instructions and examples to help you seamlessly transition to the new installation methods:

* [Overview and details of the new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html).
* [Predefined builds migration guide](#ckeditor5/latest/updating/nim-migration/predefined-builds.html).
* [Custom builds migration guide](#ckeditor5/latest/updating/nim-migration/customized-builds.html).
* [DLLs migration guide](#ckeditor5/latest/updating/nim-migration/dll-builds.html).
* [Migration guide for custom plugins published as libraries](#ckeditor5/latest/updating/nim-migration/custom-plugins.html).

Our legacy installation methods are still supported, but we put them on the deprecation path. You can learn more about this in the migration guide’s [deprecation timelines](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--sunset-of-old-installation-methods-and-deprecation-timelines) section.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--javascript-target-changed">

##### JavaScript target changed

The predefined and DLL builds are targeting the ES2022 syntax to make use of native support for class fields and methods.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--removal-of-superbuild-and-predefined-builds-from-the-cdn">

##### Removal of superbuild and predefined builds from the CDN

We have stopped publishing the superbuild and predefined builds to our CDN. Predefined builds can still be accessed as an npm package. If you want to keep using our CDN with new versions of the editor, we recommend [migrating to the new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--browser-builds).

<a id="ckeditor5/latest/updating/guides/update-to-42.html--deprecation-of-the-vite-plugin">

##### Deprecation of the Vite plugin

We have deprecated the Vite plugin, [@ckeditor/vite-plugin-ckeditor5](https://www.npmjs.com/package/@ckeditor/vite-plugin-ckeditor5), as it remained experimental and did not fully support features such as translations handling. The newly introduced installation methods resolve this issues, as they work with any bundler out-of-the-box.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--new-builder">

#### New Builder

Along with the new release, we present you the brand new [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/).

The new Builder allows you to start with one of the predefined presets, customize it by adding and removing features, and observe the changes live in an editor preview (and play with the editor!). Once you are happy with your custom setup, you get ready-to-use code snippets for React, Angular, Vue, and VanillaJS setups for both npm and CDN distributions.

<a id="ckeditor5/latest/updating/guides/update-to-42.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **[image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image)**: The `Insert image via URL` UI component form has been moved to a modal dialog instead of being available directly in the insert image dropdown.
* **[image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image)**: Increased specificity of the `.image-style-block-align-[right/left]`, `.image-style-align-[right/left]`, and `.image-style-side` CSS classes by adding the `.image` class. See [#16317](https://github.com/ckeditor/ckeditor5/issues/16317).
* **[media-embed](https://www.npmjs.com/package/@ckeditor/ckeditor5-media-embed)**: The media embed feature now uses a modal dialog (instead of a toolbar dropdown) for inserting media.
* **[pagination](https://www.npmjs.com/package/@ckeditor/ckeditor5-pagination)**: If you have custom CSS styles that override the default styling of the `Pagination` elements, they might stop working after this change. The reason is that a stricter CSS selector with `ck-pagination-loaded` is now used to hide or show these elements.

<a id="ckeditor5/latest/updating/guides/update-to-43.html">source file: "ckeditor5/latest/updating/guides/update-to-43.html"</a>

## Update to CKEditor 5 v43.x

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4331">

### Update to CKEditor 5 v43.3.1

Released on November 6, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.3.1))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.3.1.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--reverted-icon-change">

#### Reverted icon change

We had to revert a change introduced in v43.3.0 related to the icons export in one of our packages. This was due to unforeseen TypeScript issues in some setups.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4330">

### Update to CKEditor 5 v43.3.0

Released on October 29, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.3.0))

For the entire list of changes introduced in version 43.3.0, see the [release notes for CKEditor 5 v43.3.0](https://github.com/ckeditor/ckeditor5/releases/tag/v43.3.0).

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.3.0.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--performance-improvements">

#### Performance improvements

We have improved how the editor handles the document structure by making it more reliable and efficient to access specific elements and verify their positions.

* **Node index and offset caching**: The `Node` and `NodeList` elements now cache index and offset values, reducing the need for recalculations and significantly boosting overall performance during model operations.
* **Selection range validation**: The newly implemented `Position#isValid()` method is also utilized to better validate selection ranges, ensuring more consistent behavior in various editing scenarios.
* **Performance improvements in numbers**: The editor now loads content between **3x and, in some cases, up to 6x faster, depending on the type and size of the content**. For instance, where a specific 200-page document previously took almost 25 seconds to load, the time has now been reduced to just 3.5 seconds.

**We’re committed to ongoing performance enhancements**, so you can expect even faster, smoother experience in future updates.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--export-to-word-watermark-support">

#### Export to Word watermark support

A new configuration option has been added to include a watermark when exporting documents to Word, providing additional flexibility in document branding and protection.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4320">

### Update to CKEditor 5 v43.2.0

Released on October 15, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.2.0))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.2.0.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--notable-improvements">

#### Notable improvements

* **Operational Transformation Stability**: Significant changes have been made to the OT system, enhancing the undo functionality and real-time collaboration, especially in conflict resolution scenarios. These improvements ensure smoother editor operations during complex interactions.
* **Performance Improvements**: We have merged several community-driven performance enhancements, that optimize the editor’s core engine. While no changes to the editor’s logic were made, these updates improve overall efficiency and responsiveness.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--more-imports-available-via-ckeditor5-and-ckeditor5-premium-features-indexes">

#### More imports available via `ckeditor5` and `ckeditor5-premium-features` indexes

As users transition to new installation methods (v42.0.0+) with `ckeditor5` and `ckeditor5-premium-features` as the main packages, we are continuously addressing missing imports for less common classes, functions, types, and utilities, broadening their availability. Since our TypeScript rewrite (v37.0.0), imports can now be made directly through the package indexes, simplifying integration. As many users historically imported from `src`, we encourage you to try the new version and report any missing imports. In the future, we are considering removing `src` from published packages to reduce package size, so the more feedback we receive, the better and more stable API we will provide.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4311">

### Update to CKEditor 5 v43.1.1

Released on September 25, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.1.1))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.1.0.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--vulnerability-fix">

#### Vulnerability fix

During a recent internal audit, we identified a Cross-Site Scripting (XSS) vulnerability in the CKEditor 5 clipboard package ([CVE-2024-45613](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-rgg8-g5x8-wr9v)). This vulnerability could be triggered by a specific user action, leading to unauthorized JavaScript code execution if the attacker inserted malicious content into the editor, which might happen with only a particular editor configuration.

This vulnerability affects **only** installations where the editor configuration meets the following criteria:

1. The [**Block Toolbar**](#ckeditor5/latest/getting-started/setup/toolbar.html--block-toolbar) plugin is enabled.
2. One of the following plugins is also enabled:  
  * [**General HTML Support**](#ckeditor5/latest/features/html/general-html-support.html) with a configuration that permits unsafe markup.
  * [**HTML Embed**](#ckeditor5/latest/features/html/html-embed.html).

You can read more details in the relevant [security advisory](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-rgg8-g5x8-wr9v) and [contact us](https://ckeditor.com/contact/) if you have more questions.

Taking the occasion, we decided to introduce additional hardening to some parts of our codebase that introduce **theoretical and non-exploitable issues**. Our security team confirmed that none of these issues were exploitable in a real scenario, however, we decided to fix them, to increase the overall security posture of our software.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4310">

### Update to CKEditor 5 v43.1.0

Released on September 5, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.1.0))

For the entire list of changes introduced in version 43.1.0, see the [release notes for CKEditor 5 v43.1.0](https://github.com/ckeditor/ckeditor5/releases/tag/v43.1.0).

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.1.0.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--reverted-recently-introduced-configsanitizehtml">

#### Reverted recently introduced `config.sanitizeHtml`

In v43.0.0 we made a decision to move [config.htmlEmbed.sanitizeHtml](../../api/module%5Fhtml-embed%5Fhtmlembedconfig-HtmlEmbedConfig.html#member-sanitizeHtml) to a top-level property `config.sanitizeHtml`, so it could be used by multiple features (HTML embed, merge fields, and possibly other in future).

However, we realized that it was a wrong decision to expose such a sensitive property in a top-level configuration property. We are worried that integrators may be confused and incorrectly assume that this callback would sanitize the entire output from CKEditor. Therefore, we decided to revert that change, so the sanitization callback is related strictly with the features that use it.

Starting with v43.1.0, you should again use [config.htmlEmbed.sanitizeHtml](../../api/module%5Fhtml-embed%5Fhtmlembedconfig-HtmlEmbedConfig.html#member-sanitizeHtml) and newly introduced [config.mergeFields.sanitizeHtml](../../api/module%5Fmerge-fields%5Fmergefieldsconfig-MergeFieldsConfig.html#member-sanitizeHtml). The editor will throw an error if `config.sanitizeHtml` is used.

Note: CKEditor 5, by default, prevents execution of scripts in the editor content, while the content is being edited inside the editor. However, there are features (such as General HTML support or HTML embed) that can be configured to make CKEditor 5 produce HTML output that contains executable scripts. Please remember, that CKEditor 5 is a frontend component working in a browser. As an integrator, it is your responsibility to sanitize the content before it is displayed on your website or on other potentially vulnerable medium.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--table-and-cell-border-settings-update">

#### Table and cell border settings update

The tables’ user interface now clearly indicates the default border settings. It allows users to set “no borders” (None) for tables and cells without any additional configuration.

⚠️ In some cases this update may lead to data changes in the tables’ HTML markup when the editor loads them. However, visually nothing will change, and the experience will be the same.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-to-ckeditor-5-v4300">

### Update to CKEditor 5 v43.0.0

Released on August 7, 2024\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v43.0.0))

For the entire list of changes introduced in version 43.0.0, see the [release notes for CKEditor 5 v43.0.0](https://github.com/ckeditor/ckeditor5/releases/tag/v43.0.0).

Below are the most important changes that require your attention when upgrading to CKEditor 5 v43.0.0.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--export-to-word-v2-becomes-the-default">

#### Export to Word v2 becomes the default

In CKEditor 5 v42.0.0, we introduced a new version of the Export to Word plugin that utilizes the updated converter (marked as V2). It was introduced in an opt-in manner. Starting with v43.0.0, the Export to Word V2 is **the default** configuration. This may require updates to the editor’s configuration if you use this plugin.

Example V1 configuration:

```
exportWord: {
    tokenUrl: 'https://example.com/cs-token-endpoint',
    fileName: 'my-file.docx',
    converterOptions: {
        format: 'A4',
        margin_top: '20mm',
        margin_bottom: '20mm',
        margin_right: '12mm',
        margin_left: '12mm'
    }
}

```

The same migrated to V2:

```
exportWord: {
    tokenUrl: 'https://example.com/cs-token-endpoint',
    fileName: 'my-file.docx',
    converterOptions: {
        document: {
            size: 'A4',
            margin: {
                top: '20mm',
                bottom: '20mm',
                right: '12mm',
                left: '12mm'
            }
        }
    }
}

```

You can find the full V2 configuration in the [ExportWordConverterOptionsV2](../../api/module%5Fexport-word%5Fexportword-ExportWordConverterOptionsV2.html) API documentation.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--other-configuration-changes">

##### Other configuration changes

* We decided to switch the default `auto_pagination` option to `false`. This option was only used with the [pagination feature](#ckeditor5/latest/features/pagination/pagination.html). When enabled, the breaks in the pagination force page breaks in the exported Word document. However, browser engines and Microsoft Word differ significantly in how they render page elements. Because of that we decided to turn this option off. If you still want to enforce breaks from pagination, change it in the configuration to `true`.
* A new configuration option was added: `document.language`. It is set to the editor content language by default.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--typing-bug-fixes">

#### Typing bug fixes

This release brings a couple of improvements to typing in the editor.

* Android IME: multiple issues related to duplicated characters, reverse writing effects, etc. ([#13994](https://github.com/ckeditor/ckeditor5/issues/13994), [#14707](https://github.com/ckeditor/ckeditor5/issues/14707), [#13850](https://github.com/ckeditor/ckeditor5/issues/13850), [#13693](https://github.com/ckeditor/ckeditor5/issues/13693), [#14567](https://github.com/ckeditor/ckeditor5/issues/14567), [#11569](https://github.com/ckeditor/ckeditor5/issues/11569)).
* Safari: the reverse typing effect after the focus change ([#14702](https://github.com/ckeditor/ckeditor5/issues/14702)).

These fixes do not require migration, but typing is a crucial area for the editor, and we want to call them out explicitly.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--special-characters-user-interface">

#### Special characters user interface

The special characters UI has been changed from a dropdown to a dialog. This unifies the action between the menu bar and the toolbar. It also gives content creators quicker access to the always-on-top dialog when they insert a lot of symbols into the content.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--update-of-global-names-in-the-umd-builds">

#### Update of global names in the UMD builds

We have decided to change the global names for the `ckeditor5` and `ckeditor5-premium-features` packages in the UMD builds to `CKEDITOR` and `CKEDITOR_PREMIUM_FEATURES` respectively.

<a id="ckeditor5/latest/updating/guides/update-to-43.html--react-and-vue-integrations-updates">

#### React and Vue integrations updates

We have released new major versions of the React and Vue integrations. In both of them, we have migrated to JavaScript modules (ESM) and rewritten large parts of their codebases to support the latest versions of these frameworks and to follow the latest recommendations for writing the components.

We strongly recommend that you read the release highlights to update to the latest versions:

* [Release highlights for React integration](https://github.com/ckeditor/ckeditor5-react/releases/tag/v9.0.0).
* [Release highlights for Vue integration](https://github.com/ckeditor/ckeditor5-vue/releases/tag/v7.0.0).

<a id="ckeditor5/latest/updating/guides/update-to-43.html--updates-to-the-package-generator">

#### Updates to the Package Generator

In the last major release of CKEditor 5, we introduced new installation methods. Since then we have received a lot of feedback from you. Thanks to this, we identified several minor issues fixed in versions 42.0.1 and 42.0.2\. While these fixes did not require any changes in the application, they do require some changes in the custom plugins created with the Package Generator.

You can skip this section if you have not read the [Migrating custom plugins](#ckeditor5/latest/updating/nim-migration/custom-plugins.html) guide. However, if you have, follow the steps below to apply these fixes to your plugin.

1. Update all packages starting with `@ckeditor/ckeditor5-dev-` to version `^42.0.0`.
2. Open the `package.json` file and replace the content as follows:

  * If your project is written in TypeScript, replace the `"types"` and `"exports"` fields:  
  ```  
  "types": "dist/index.d.ts",  
  "exports": {  
      ".": {  
          "types": "./dist/index.d.ts",  
          "import": "./dist/index.js"  
      },  
      "./*": "./dist/*",  
      "./browser/*": null,  
      "./package.json": "./package.json"  
  }  
  ```
  * If your project is written in plain JavaScript, replace the `“exports”` field:  
  ```  
  "exports": {  
      ".": "./dist/index.js",  
      "./*": "./dist/*",  
      "./browser/*": null,  
      "./package.json": "./package.json"  
  }  
  ```
3. Open the `scripts/build-dist.mjs` file and look for the `name` object key in the second `build()` step. This value represents the global variable under which your plugin is available in the UMD build and should currently match the name of your package. UMD is an alternative build format that we provide for those who cannot use JavaScript modules in their applications. We encourage you to update this value to `CKEDITOR_PLUGIN_X`, where `X` uniquely identifies your plugin. We recommend using only uppercase letters and underscores (`_`).

<a id="ckeditor5/latest/updating/guides/update-to-43.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **Reverted `config.sanitizeHtml`.** In v43.0.0 we made a decision to move `config.htmlEmbed.sanitizeHtml` to a top-level property `config.sanitizeHtml`. However, we realized that it was a wrong decision to expose such a sensitive property in a top-level configuration property. Starting with v43.1.0 you should again use `config.htmlEmbed.sanitizeHtml` and/or `config.mergeFields.sanitizeHtml`. The editor will throw an error if `config.sanitizeHtml` is used. See the [migration guide](#ckeditor5/latest/updating/guides/update-to-43.html--reverted-recently-introduced-configsanitizehtml) for additional context behind this decision.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The structure and presentation of the list of AI commands in the toolbar have changed (a flat filtered list is now a nested menu). Additionally, if your integration customizes this user interface, please ensure your integration code is up-to-date.
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: The default `[aria-label]` provided by `InlineEditableUIView` is now `'Rich Text Editor. Editing area: [root name]'` (previously: `'Editor editing area: [root name]'`). You can use the `options.label` constructor property to adjust the label.

<a id="ckeditor5/latest/updating/guides/update-to-44.html">source file: "ckeditor5/latest/updating/guides/update-to-44.html"</a>

## Update to CKEditor 5 v44.x

<a id="ckeditor5/latest/updating/guides/update-to-44.html--update-to-ckeditor-5-v4430">

### Update to CKEditor 5 v44.3.0

Released on March 5, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v44.3.0))

<a id="ckeditor5/latest/updating/guides/update-to-44.html--fixed-link-decorators">

#### Fixed link decorators

We fixed the behavior of the multiple manual link decorators that set the `rel` attribute. The fix happened so deep in the engine that we improved the overall performance of the editor slightly as well.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--new-emptyblock-plugin">

#### New `EmptyBlock` plugin

Starting this release, a new [EmptyBlock](../../api/module%5Fhtml-support%5Femptyblock-EmptyBlock.html) plugin prevents adding `&nbsp;` to the output data of blocks, and works similarly to the [fillEmptyBlocks](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-fillEmptyBlocks) configuration in CKEditor 4.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--enhanced-support-for-the-hr-element">

#### Enhanced support for the `<hr>` element

We have enhanced support for the `<hr>` element in the [General HTML Support](#ckeditor5/latest/features/html/general-html-support.html) plugin. Now, the attributes of the `<hr>` element are properly preserved if configuration allows it.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--enhanced-emoji-support">

#### Enhanced emoji support

We enhanced emoji support for better compatibility with users’ devices.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: The `ViewConsumable.consumablesFromElement()` is removed and replaced with the `view.Element#_getConsumables()` internal method. You should use `ViewConsumable.createFrom()` to create consumables if needed.
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: The `ViewElementConsumables` now accepts and outputs only normalized data. The `ViewConsumable` still accepts normalized or non-normalized input.
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: The `Matcher#match()` and `Matcher#matchAll()` output is now normalized. The `MatchResult#match` now contains normalized data compatible with changes in the `ViewConsumable`.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--update-to-ckeditor-5-v4421">

### Update to CKEditor 5 v44.2.1

Released on February 20, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v44.2.1))

<a id="ckeditor5/latest/updating/guides/update-to-44.html--vulnerability-removed">

#### Vulnerability removed

During a recent internal audit, we identified a cross-site scripting (XSS) vulnerability in the CKEditor 5 real-time collaboration package ([CVE-2025-25299](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-j3mm-wmfm-mwvh)). This vulnerability can lead to unauthorized JavaScript code execution and affects user markers, which represent users’ positions within the document.

This vulnerability affects only installations with [real-time collaborative editing](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) enabled.

You can read more details in the relevant [security advisory](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-j3mm-wmfm-mwvh) and [contact us](mailto:security@cksource.com) if you have more questions.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--update-to-ckeditor-5-v4420">

### Update to CKEditor 5 v44.2.0

Released on February 12, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v44.2.0))

<a id="ckeditor5/latest/updating/guides/update-to-44.html--enhanced-source-code-editing">

#### Enhanced Source Code Editing

Introducing new premium feature with current release: the [enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html). It displays the source code in a dialog and is compatible with all editor types. It also offers syntax highlighting, code completion, code folding, and other advanced functionalities. Additionally, it supports both HTML and Markdown formats.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--uploadcare-and-image-optimizer">

#### Uploadcare and image optimizer

We have integrated the [Uploadcare](https://uploadcare.com/) image manager service, offering our users yet another way to upload and edit images in their cloud environment. You can upload files from various sources, including local devices, social media, or online drives ensuring rapid uploads. The integration takes care of efficient media delivery with responsive images mechanism, making sure your users will save bandwidth and have faster website loading. You can also optimize images with the built-in image editor which offers a range of features, such as cropping, rotating, flipping, photo filters and more. All this can be done directly from the editor. [Try it out](#ckeditor5/latest/features/file-management/uploadcare.html)!

<a id="ckeditor5/latest/updating/guides/update-to-44.html--image-merge-fields">

#### Image Merge Fields

The [image merge fields](#ckeditor5/latest/features/merge-fields.html--template-editing) are a new type of merge fields, dedicated for image placeholders. They maintain all standard image interactions, like styling, resizing or captions (in which you can use merge fields too!) At the same time, they keep all merge fields functionalities, like data previews or document export integration. In the document data, image merge fields are represented like other images, however their `src` attribute is set to a respective merge field, for example, `src="{{CompanyLogo}}"`, making them easy to post-process!

<a id="ckeditor5/latest/updating/guides/update-to-44.html--track-changes-preview">

#### Track Changes Preview

We have added the [track changes preview mode](#ckeditor5/latest/features/collaboration/track-changes/track-changes-preview.html) that displays a document with all suggestions accepted. Accessible from the track changes dropdown, this modal preview helps check the final content without extensive markers.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--emoji-support">

#### Emoji support

With the new [feature](#ckeditor5/latest/features/emoji.html) you can insert emojis effortlessly in the editor by typing `:` or through a user-friendly emoji picker. This feature enhances the richness of your content by allowing quick access to a wide range of emojis.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--performance-improvements">

#### Performance improvements

Here comes the final batch of the planned performance improvements in the editor loading speed area, that we worked on through a couple of past releases.

* A new caching mechanism in `Mapper` now handles model-to-view mappings, substantially improving performance for loading and saving data.
* Images with specified height and width automatically use `[loading="lazy"]` in the editing area, optimizing the loading time ([read more on MDN](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy%5Floading#images%5Fand%5Fiframes)). This attribute is only applied during editing to enhance the loading efficiency of images, and it does not reflect in the final data output.

We are greatly satisfied with the improved editor loading times. At the same time, we acknowledge some other problematic areas, and we will keep delivering more performance-related improvements in the future.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--minor-breaking-changes-in-this-release-2">

#### Minor breaking changes in this release

* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: `Mapper#registerViewToModelLength()` is now deprecated and will be removed in one of the upcoming releases. This method is useful only in obscure and complex converters, where model element, or a group of model elements, are represented differently in the view. We believe that every feature using a custom view-to-model length callback can be rewritten in a way that this mechanism is no longer necessary. Note: if this method is used, the caching mechanism for `Mapper` will be turned off which may degrade performance when handling big documents. Note: this method is used by the deprecated legacy lists feature. As a result, you will not experience the performance improvements if you are still using the deprecated legacy lists feature.
* **[image](https://www.npmjs.com/package/@ckeditor/ckeditor5-image)**: Starting this release, images that have `[height]` and `[width]` attributes set will automatically receive the `[loading="lazy"]` attribute in the editing area. This happens only for the content loaded into the editor, the data output produced by the editor remains the same. The reason for this change is to improve user experience in documents that may contain hundreds of images.
* **[list](https://www.npmjs.com/package/@ckeditor/ckeditor5-list)**: The `lower-alpha` and `upper-alpha` list styles are now upcasted to `lower-latin` and `upper-latin` styles.
* **[merge-fields](https://www.npmjs.com/package/@ckeditor/ckeditor5-merge-fields)**: The `MergeFieldsEditing#getLabel()` method will now return `null` instead of the merge field id if the merge field definition was not found or it did not contain the `label` property.
* **[basic-styles](https://www.npmjs.com/package/@ckeditor/ckeditor5-basic-styles)**: Elements which contains the `[style]` attribute with `word-wrap: break-word` will not be converted to `<code>`. See [#17789](https://github.com/ckeditor/ckeditor5/issues/17789).

<a id="ckeditor5/latest/updating/guides/update-to-44.html--update-to-ckeditor-5-v4410">

### Update to CKEditor 5 v44.1.0

Released on December 16, 2024 ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v44.1.0)).

<a id="ckeditor5/latest/updating/guides/update-to-44.html--minor-breaking-changes-in-this-release-3">

#### Minor breaking changes in this release

* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: `spliceArray` now modifies the target array and does not accept a fourth (`count`) argument.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--update-to-ckeditor-5-v4400">

### Update to CKEditor 5 v44.0.0

Released on December 2, 2024 ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v44.0.0)).

For the entire list of changes introduced in version 44.0.0, see the [release notes for CKEditor 5 v44.0.0](https://github.com/ckeditor/ckeditor5/releases/tag/v44.0.0).

Below are the most important changes that require your attention when upgrading to CKEditor 5 v44.0.0.

<a id="ckeditor5/latest/updating/guides/update-to-44.html--required-license-key-configuration">

#### Required license key configuration

Version 44.0.0 introduced a change in the license configuration. The `config.licenseKey` is now a required property in the editor configuration. Whether you are using CKEditor 5 commercially or under open-source terms, you will need to specify this property in your configuration.

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        licenseKey: '<YOUR_LICENSE_KEY>' // Or 'GPL'.

        // ... Other configuration options ...

    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

* **Commercial licenses**: When upgrading to version 44.0.0 or later, users with a commercial license must update their license key to the [new format](#ckeditor5/latest/updating/guides/update-to-44.html--new-license-key-format). To update your license key, log in to the [Customer Portal](https://portal.ckeditor.com/) and copy the key associated with your subscription into your editor’s configuration.
* **Open-source installations**:  
  * **Self-hosted (npm/ZIP) installations**: If you are self-hosting CKEditor 5 under the [GPL 2+ terms](#ckeditor5/latest/getting-started/licensing/license-and-legal.html) or as a part of our [Open Source support project](https://ckeditor.com/wysiwyg-editor-open-source/), you need to set `config.licenseKey` to `'GPL'` in your configuration.
  * **Cloud (CDN) installations**: For cloud-distributed CKEditor 5 served via [our CDN](https://cdn.ckeditor.com), you must obtain a license key from the Customer Portal. Create a [free account](https://portal.ckeditor.com/checkout?plan=free) and add the provided license key to your editor configuration.  
  During the 14-day trial (automatically activated upon sign-up), you can explore all Premium Features. After the trial ends, usage metering and editor load limits specific to your chosen plan will apply. Learn more about [available plans](https://ckeditor.com/pricing/) and [usage-based billing](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html).

Read more in our guides about [license keys](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) and [usage-based billing](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html).

<a id="ckeditor5/latest/updating/guides/update-to-44.html--new-license-key-format">

#### New license key format

A new license key format has been introduced. Previous license keys **will no longer work** after updating the editor to version 44.0.0 and above.

We also changed the way the development license key works. To prevent it from accidental usage on production it is limited only to development domains, shows informational label, and has operational limit. [Read more about the details](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html--development-license-key).

Acquiring new keys:

1. **Access the Customer Portal**: Log in to the [Customer Portal](https://portal.ckeditor.com/) to obtain your new license key.
2. **Update configuration**: Replace the old license key in your editor configuration with the new key.

For more information or assistance, please refer to our [documentation](#ckeditor5/latest/getting-started/licensing/license-key-and-activation.html) or [contact our support team](https://ckeditor.com/contact/).

<a id="ckeditor5/latest/updating/guides/update-to-44.html--self-service-plans-and-new-customer-portal">

#### Self-service plans and new Customer Portal

The new self-service plans make accessing CKEditor Premium Features easier than ever. You can now choose the plan that best suits your needs and get started quickly with commitment-free trials.

Plans are managed through a new, dedicated [Customer Portal](https://portal.ckeditor.com/), where you can access license keys, track usage, manage billing, and submit support requests-all from one place.

Learn more about the [different plans available](https://ckeditor.com/pricing/) or start your [14-day free trial](https://portal.ckeditor.com/checkout?plan=free).

<a id="ckeditor5/latest/updating/guides/update-to-44.html--major-breaking-changes-in-this-release">

#### Major breaking changes in this release

* `config.licenseKey` is now a required property in the editor configuration. Use `'GPL'` for installations under the GPL terms. See [#17317](https://github.com/ckeditor/ckeditor5/issues/17317).

<a id="ckeditor5/latest/updating/guides/update-to-45.html">source file: "ckeditor5/latest/updating/guides/update-to-45.html"</a>

## Update to CKEditor 5 v45.x

<a id="ckeditor5/latest/updating/guides/update-to-45.html--update-to-ckeditor-5-v4522">

### Update to CKEditor 5 v45.2.2

Released on 3 September, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v45.2.2))

A Cross-Site Scripting (XSS) vulnerability has been discovered in the CKEditor 5 clipboard package (`CVE-2025-58064`). This vulnerability could be triggered by a specific user action, leading to unauthorized JavaScript code execution, if the attacker managed to insert malicious content into the editor, which might happen with a specific editor configuration.

This vulnerability affects **only** installations where the editor configuration meets one of the following criteria:

* The [HTML embed plugin](#ckeditor5/latest/features/html/html-embed.html) is enabled
* A custom plugin introducing an editable element that implements the view [RawElement](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fview%5Frawelement-ViewRawElement.html) is enabled

For more details, please refer to the relevant [security advisory](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-x9gp-vjh6-3wv6) and [contact us](https://ckeditor.com/contact/) if you have more questions.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--update-to-ckeditor-5-v4521">

### Update to CKEditor 5 v45.2.1

Released on June 24, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v45.2.1))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v45.2.1.

* Fixed editor crash that happened in a specific scenario, when editing heavily formatted text, text with multiple comments, or text with comments and formatting.
* Fixed incorrect cache invalidation in `Mapper`, which could lead to crashes when editing heavily formatted content or when using complex features like multi-level lists.
* Fixed editor crash that happened when typing over a table content with the balloon toolbar enabled.
* Fixed editor crash that happened when editing deeply nested multi-level lists.
* Improved calculation of pagination page-breaks on documents with long tables.
* Fixed editor crash when typing over multiple selected blocks next to a code block or a block quote.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--update-to-ckeditor-5-v4520">

### Update to CKEditor 5 v45.2.0

Released on June 4, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v45.2.0))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v45.2.0.

* We fixed the copy-paste scenario in the read-only mode.
* Tables pasted from Office, especially with borderless layouts, should preserve styling in the editor similar to the ones in the source file.
* Improved the adoption of the fullscreen feature on smaller screens and includes subtle visual tweaks.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **[source-editing](https://www.npmjs.com/package/@ckeditor/ckeditor5-source-editing)**: The `formatHtml()` helper function is extracted to the `@ckeditor/ckeditor5-utils` package. See [#18480](https://github.com/ckeditor/ckeditor5/issues/18480).

<a id="ckeditor5/latest/updating/guides/update-to-45.html--update-to-ckeditor-5-v4510">

### Update to CKEditor 5 v45.1.0

Released on May 14, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v45.1.0))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v45.1.0.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--typing-improvements">

#### Typing Improvements

The typing behavior has been improved for plain text typing. This adjustment allows the web browser to handle text insertion before the editor processes it, enhancing typing reliability across various scenarios, especially on Safari and iOS devices. Issues related to track changes, autocorrect, automatic text replacement, and other input methods have been addressed.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--track-changes-enhancements">

#### Track Changes Enhancements

A new method to start a “tracking session” has been introduced, preventing automatic merging of adjacent suggestions. This allows for more precise control over individual changes, catering to workflows that require selective acceptance of edits.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--miscellaneous-improvements">

#### Miscellaneous improvements

* Sticky toolbars and balloons are now better aligned with the visual viewport on iOS and Safari, ensuring correct positioning when zooming.
* The fullscreen plugin has been improved to maintain scroll position when exiting fullscreen, avoiding unexpected jumps on smooth-scrolling pages. Layout consistency has been refined by adjusting margins and editable width. Errors related to the Content minimap plugin in fullscreen mode have also been resolved.
* Introduced a fix which ensures that the `data-author-id` and `data-suggestion` attributes are preserved in non-block suggestions when retrieving data with `showSuggestionHighlights: true`.
* We improved the algorithm for images detection in the Paste from Office feature, in scenarios of mixed local and online images from Microsoft Word. Paste no longer causes some images not to appear.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--minor-breaking-changes-in-this-release-2">

#### Minor breaking changes in this release

The default behavior of the `beforeinput` DOM events is no longer prevented in plain text typing scenarios. Now, the engine waits for DOM mutations and applies changes to the model afterward. This should not affect most integrations however, it may affect custom modifications to text insertion into the editor.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--update-to-ckeditor-5-v4500">

### Update to CKEditor 5 v45.0.0

Released on April 7, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v45.0.0))

Below are the most important changes that require your attention when upgrading to CKEditor 5 v45.0.0.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--email-editing-enhancements">

#### Email editing enhancements

We are making it easier to create and edit emails directly in CKEditor 5 with several enhancements. This release introduces the following new features:

* [Export with Inline Styles](#ckeditor5/latest/features/export-with-inline-styles.html) (⭐) provides the ability to export email content with automatically inlined styles, ensuring compatibility and proper rendering across different email clients.
* [Email Configuration Helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html) (⭐) is a new configuration helper plugin that provides guidance for integrators to correctly set up an email-friendly editor while avoiding common pitfalls.
* [Layout tables](#ckeditor5/latest/features/tables/layout-tables.html) are a new type of tables that has been introduced to simplify the creation of structured email designs, offering better control over layout, alignment and spacing.

Apart from these new features, this update also brings various fixes and improvements related to table behavior, enhanced HTML support, and better handling of complex email structures. These refinements help ensure a more seamless email editing experience, reducing inconsistencies and improving compatibility with external email clients.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--the-fullscreen-feature">

#### The fullscreen feature

A long-requested feature has finally arrived with the [introduction of full-screen editing](#ckeditor5/latest/features/fullscreen.html) for the classic and decoupled editor types. This new mode provides a focused writing experience by making the editor the centerpiece of the screen. The expanded screen space allows for better visibility of content in sidebars such as comments, suggestions, and document outlines, enhancing your overall workflow.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--ui-toolbar-refactoring">

#### UI toolbar refactoring

The [link](#ckeditor5/latest/features/link.html) and [bookmark](#ckeditor5/latest/features/bookmarks.html) features have been refactored to use standard toolbar components, making them more customizable and consistent:

<a id="ckeditor5/latest/updating/guides/update-to-45.html--link-feature-changes">

##### Link feature changes

The link UI has been refactored to allow for easier customization of the link toolbar through configuration. The most notable changes include:

* The custom `LinkActionsView` has been replaced with a standard `ToolbarView`. The toolbar is accessible via `LinkUI#toolbarView` instead of `LinkUI#actionsView` and configurable through the `link.toolbar` configuration option.
* Link properties (decorators) are now accessed through the toolbar instead of a separate settings panel.
* The link toolbar now uses components registered in `ComponentFactory`, making it more extensible.

Here is how to configure the link toolbar:

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            toolbar: [ 'myCustomLinkInfo', '|', 'editLink', 'linkProperties', 'unlink' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/updating/guides/update-to-45.html--bookmark-feature-changes">

##### Bookmark feature changes

The bookmark UI has been refactored to use the `WidgetToolbarRepository` instead of a custom `ActionsView`. Key changes include:

* The custom `BookmarkUI#actionsView` has been removed in favor of using the standard widget toolbar system.
* The bookmark toolbar is configurable through the `bookmark.toolbar` configuration option.
* The toolbar items are registered in `ComponentFactory` and can be customized.

For bookmark features, you can configure the toolbar like this:

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        bookmark: {
            toolbar: [ 'bookmarkPreview', '|', 'editBookmark', 'removeBookmark' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/updating/guides/update-to-45.html--custom-toolbar-components">

#### Custom toolbar components

The link and bookmark features now allow custom toolbar items to be registered in their respective toolbars. To add a custom item:

1. Register it in the component factory
2. Add it to the toolbar configuration

Below is an example of registering a custom component:

```
editor.ui.componentFactory.add( 'myCustomLinkInfo', locale => {
    const button = new ButtonView( locale );
    const linkCommand = editor.commands.get( 'link' );

    button.bind( 'isEnabled' ).to( linkCommand, 'value', href => !!href );
    button.bind( 'label' ).to( linkCommand, 'value' );

    button.on( 'execute', () => {
        // Add your custom component logic here
    } );

    return button;
} );

```

Once registered, the component can be used in the toolbar configuration:

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            toolbar: [ 'myCustomLinkInfo', '|', 'editLink', 'unlink' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

For a complete list of available toolbar items and configuration options, see the [link configuration documentation](../../api/module%5Flink%5Flinkconfig-LinkConfig.html#member-toolbar) and [bookmark configuration documentation](../../api/module%5Fbookmark%5Fbookmarkconfig-BookmarkConfig.html#member-toolbar).

<a id="ckeditor5/latest/updating/guides/update-to-45.html--link-provider-registration">

#### Link provider registration

The link UI now supports registering custom link providers through the new `LinkUI#registerLinksListProvider` method. This allows for adding a list of predefined links available in the link form. Here is a simple example:

```
editor.plugins.get( 'LinkUI' ).registerLinksListProvider( {
    label: 'My links',

    // Return a list of links to display in the link form
    getListItems: () => [
        {
            id: 'homepage',
            href: 'https://example.com',
            label: 'Homepage',
            icon: linkIcon
        }
    ],

    // Optional: Customize how links are displayed in preview
    getItem: href => {
        return {
            href,
            label: 'My custom label',
            tooltip: 'Open link'
        };
    }
} );

```

The registered links will appear as a button in the link form, allowing users to quickly insert commonly used links.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--other-code-changes">

##### Other code changes

* The `createBookmarkCallbacks()` helper has been replaced with the `isScrollableToTarget()` and `scrollToTarget()` helpers.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--unified-form-styles">

#### Unified form styles

Form components across various features (link, bookmark, image, table) have been unified using the new `ck-form` and `ck-form__row` classes. The form styling has been centralized in the `theme-lark` package.

Notable changes:

* A new `FormRowView` class has been introduced in the UI package for consistent form row layouts.
* All balloon panels now have consistent headers with back buttons.
* Form styles have been moved to a dedicated `form.css` in the theme-lark package.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--new-installation-methods-improvements-icons-replacement">

#### New installation methods improvements: icons replacement

We are continuing to strengthen the new installation methods while phasing out older solutions. We added one of the key components you asked for: replacing our icons with your custom ones. It is now possible to replace the icons via the [package’s override mechanism](#ckeditor5/latest/getting-started/setup/customizing-icons.html).

<a id="ckeditor5/latest/updating/guides/update-to-45.html--deprecations-in-old-installation-methods-stage-1-completed">

#### Deprecations in old installation methods: stage 1 completed

We are progressing with deprecation according to [our sunset plan](https://github.com/ckeditor/ckeditor5/issues/17779). From this release, predefined builds’ packages, such as `@ckeditor/ckeditor-build-classic`, are now officially deprecated.

We also dropped support for Webpack 4 in both the **old and new** installation methods. All packages and CDN from this version are now distributed with ES2022 as the target ECMAScript version, providing better compatibility with modern JavaScript features and improved performance.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--major-breaking-changes-in-this-release">

#### Major breaking changes in this release

* **[bookmark](https://www.npmjs.com/package/@ckeditor/ckeditor5-bookmark)**: The `BookmarkUI#actionsView` is no longer available. The bookmark feature is now using the `WidgetToolbarRepository` instead.
* **[build-\*](https://www.npmjs.com/search?q=keywords%3Ackeditor5-build%20maintainer%3Ackeditor)**: CKEditor 5 predefined builds are no longer available.
* **[link](https://www.npmjs.com/package/@ckeditor/ckeditor5-link)**: The `LinkUI#actionsView` is no longer available. The bookmark feature now uses the `LinkUI#toolbarView` (an instance of the `ToolbarView` class) instead of the custom `LinkActionsView`.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--minor-breaking-changes-in-this-release-3">

#### Minor breaking changes in this release

* **[link](https://www.npmjs.com/package/@ckeditor/ckeditor5-link)**: The `createBookmarkCallbacks()` helper is now replaced by the `isScrollableToTarget()` and `scrollToTarget()` helpers.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: The `FormRowView` class was moved to the `@ckeditor/ckeditor5-ui` package.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: The `form.css` component was moved to the `@ckeditor/ckeditor5-theme-lark` package.
* All CKEditor 5 icons are now available in the `@ckeditor/ckeditor5-icons` package.

<a id="ckeditor5/latest/updating/guides/update-to-45.html--distribution-changes">

#### Distribution changes

* All packages and CDN source code now target ES2022 as the ECMAScript version.

<a id="ckeditor5/latest/updating/guides/update-to-46.html">source file: "ckeditor5/latest/updating/guides/update-to-46.html"</a>

## Update to CKEditor 5 v46.x

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4611">

### Update to CKEditor 5 v46.1.1

Released on 15 September, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.1.1))

This is an internal release focused on improving our development infrastructure and the release process. These changes have no impact on integrators but represent significant improvements to our development workflow.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--development-environment-modernization">

#### Development environment modernization

We have migrated our package management from Yarn Classic to pnpm, unlocking significant advantages:

* Faster installations through efficient linking mechanisms,
* Improved dependency management with stricter resolution and better peer dependency handling,
* Better disk efficiency by eliminating duplicate packages across projects.

We have also introduced dependency locking mechanisms that provide greater stability and predictability in our build process, ensuring consistent environments across development setups and CI/CD pipelines.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--what-this-means-for-you">

#### What this means for you

As an integrator, you will not notice any changes in functionality or API. This release maintains full backward compatibility while laying the foundation for more efficient development cycles and faster future releases.

If you fork the repository and develop using source code, you will need to update your development setup according to our [development environment guide](#ckeditor5/latest/framework/contributing/development-environment.html).

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4610">

### Update to CKEditor 5 v46.1.0

Released on 10 September, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.1.0))

A minor stability update with focused fixes and UX improvements.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--smoother-drag-drop-of-widgets-on-ios">

#### Smoother drag & drop of widgets on iOS

We updated the implementation for more reliable drag-and-drop on iOS touch devices. The behavior on the desktop devices remains unchanged.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--pagination-improvements">

#### Pagination improvements

We reverted a low-level change to improve stability in pagination, especially in scenarios including long tables.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--hide-a-user-in-the-server-side-editing-api">

#### Hide a user in the Server-side editing API

[The Server-side editor API](#ckeditor5/latest/features/cloud-services/server-side-editor-api.html) now supports a `hidden_in_presence_list` user flag. You can use this mechanism to prevent automation script users from appearing in the editor’s presence list while scripts run.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--comments-markers-clean-up">

#### Comments’ markers clean up

We provided a better handling of edge cases where a marker points to a non-existing comment thread (for example, due to integrator mistakes). Such markers are now removed automatically to keep the editor stable.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **[real-time-collaboration](https://www.npmjs.com/package/@ckeditor/ckeditor5-real-time-collaboration)**: `CloudServicesCommentsAdapter#getCommentThread` no longer throws an error when a comment thread does not exist. Instead, it now returns `null`.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4603">

### Update to CKEditor 5 v46.0.3

Released on 3 September, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.3))

A Cross-Site Scripting (XSS) vulnerability has been discovered in the CKEditor 5 clipboard package (`CVE-2025-58064`). This vulnerability could be triggered by a specific user action, leading to unauthorized JavaScript code execution, if the attacker managed to insert malicious content into the editor, which might happen with a specific editor configuration.

This vulnerability affects **only** installations where the editor configuration meets one of the following criteria:

* The [HTML embed plugin](#ckeditor5/latest/features/html/html-embed.html) is enabled
* A custom plugin introducing an editable element that implements the view [RawElement](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fview%5Frawelement-ViewRawElement.html) is enabled

For more details, please refer to the relevant [security advisory](https://github.com/ckeditor/ckeditor5/security/advisories/GHSA-x9gp-vjh6-3wv6) and [contact us](https://ckeditor.com/contact/) if you have more questions.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4602">

### Update to CKEditor 5 v46.0.2

Released on 19 August, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.2))

This hotfix release resolves an issue where archived comment threads could incorrectly appear in the sidebar, ensuring they remain properly contained in the comments archive.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4601">

### Update to CKEditor 5 v46.0.1

Released on 11 August, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.1))

<a id="ckeditor5/latest/updating/guides/update-to-46.html--complete-documentation-redesign-is-here">

##### Complete documentation redesign is here

We have prepared a new theme for our documentation to enhance its quality. The new look improves readability and addresses several accessibility issues for a better experience. The redesigned navigation bar gives more useful access to various sections of the documentation, making it easier to reference guides for all our products. Improved table of contents makes browsing and finding guides easier, paired with updated search functionality. Check out the new experience yourself!

<a id="ckeditor5/latest/updating/guides/update-to-46.html--the-pagination-plugin-just-got-better">

##### The pagination plugin just got better

This release introduces a significant pagination update, along with numerous fixes. Page breaks are now calculated taking into account the content styles, bookmark markers, and with better tolerance calculation. Pagination now also finds the correct breakpoint for large tables of contents and images taller than the page.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--table-handling-with-pagination-and-export-to-pdf">

##### Table handling with pagination and export to PDF

The pagination and export to PDF features now better support tables containing one or more paragraphs. Cell margins are now correctly applied in exported tables, which improves the precision of pagination rendering.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--update-to-ckeditor-5-v4600">

### Update to CKEditor 5 v46.0.0

Released on 9 July, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v46.0.0))

CKEditor 5 v46.0.0 brings several major improvements and changes that enhance both the developer and end-user experience. This release includes significant API refinements, new features, and improvements to existing functionality. Below are the most important changes that require your attention when upgrading to CKEditor 5 v46.0.0.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--line-height-feature">

#### Line height feature (⭐)

The new [line height](#ckeditor5/latest/features/line-height.html) feature allows you to adjust the vertical spacing between lines of text, improving readability and visual harmony in your documents. This premium feature lets you set consistent line spacing across paragraphs and text blocks to enhance document accessibility and maintain visual hierarchy in your content.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--remove-format-improvements">

#### Remove Format improvements

Unneeded styles on block elements, such as tables and images, and General HTML Support nodes and attributes are finally eliminated when you hit the [remove format](#ckeditor5/latest/features/remove-format.html) button. The feature now cleans what it should, leaving the document structure untouched.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--list-markers-styling">

#### List markers styling

Working with [styled lists](#ckeditor5/latest/features/lists/lists-properties.html--list-styles) becomes more intuitive as list markers (bullets and numbers) now automatically inherit text styling properties. When you apply formatting to list text, the markers will match:

* Font size adjustments,
* Text color changes,
* Font weight modifications (bold, italic).

This improvement makes it easier to create visually consistent and professional-looking lists without additional configuration. This improvement also supports [multi-level lists](#ckeditor5/latest/features/lists/multi-level-lists.html).

**Important!** This behavior is enabled by default, which means you may experience content change when you load the content to the editor’s new version (for the better in our opinion). But if this is not something you expect, [you can opt out](#ckeditor5/latest/features/lists/lists-properties.html--disabling-marker-formatting).

<a id="ckeditor5/latest/updating/guides/update-to-46.html--markdown-processor-dependency-refresh">

#### Markdown processor dependency refresh

The [Markdown](#ckeditor5/latest/features/markdown.html) feature dependencies have been modernized with a switch to the `unified` ecosystem, replacing the previous `marked` / `turndown` implementation. This change brings more consistent and symmetrical HTML ↔ Markdown conversion. By adopting `remark` and `rehype` from the same family of tools, we have created a more reliable and maintainable implementation that will better serve your document processing needs.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--manual-token-refreshing">

#### Manual token refreshing

We have added the `config.cloudServices.autoRefresh` configuration property to disable the automatic token refresh mechanism. When it is set to `false`, the token must be refreshed manually.

This property opens up the ability to implement custom token handling if a certain use case requires this.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--unified-exports-and-renames-in-the-editor-api">

#### Unified exports and renames in the editor API

This release is also about tidying up the rough edges that showed up after the big New Installation Method release (v42.0.0+). In cases where many helpers or methods from the framework’s APIs were used, some developers upgrading from v41.x to v42.x were greeted by the `does not provide an export named …` error. We addressed issues immediately as they were reported, but we knew it required a deeper are more comprehensive approach long-term.

We spent the last several months discussing how to prepare the CKEditor 5 API layer for the years to come. This release is the result of the rules we are introducing from now on:

* Every public API must be exported via the package’s `index.ts`.
* Every internal API must be marked as such explicitly with `@internal`.
* Exported names should follow a descriptive and unique naming pattern aligned with their purpose and context.
* There should be no `export default` or `export * from` statements in source files.

This resulted in:

* Adding re-exports if they were missing.
* Changing the names of items to be more descriptive and avoid collisions.
* If there were internal methods that were already exported but not tagged, we decided to keep them exported but with the addition of the `_` prefix. This way we keep them available, but we would love to know how you are using them.
* Also, we decided to use this occasion to clean up the code from `@deprecated` code that was stale for several years.

At the same time, we have developed an internal tooling to make sure guardrails are set for the future.

If your build throws errors after the update, search and replace the old names with the new ones from the [update guide](#ckeditor5/latest/updating/nim-migration/migrating-imports.html). **We have not changed the behavior of these APIs, just the names**.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--introduction-of-the-default-content-styles">

#### Introduction of the default content styles

To improve the out-of-the-box experience and accessibility, we are introducing opinionated defaults for content styling. From this version, we ship a small defaults layer applied to `.ck-content`:

```

:root {
    --ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif;
    --ck-content-font-size: medium;
    --ck-content-font-color: #000;
    --ck-content-line-height: 1.5;
    --ck-content-word-break: break-word;
}

.ck-content {
    font-family: var(--ck-content-font-family);
    font-size: var(--ck-content-font-size);
    color: var(--ck-content-font-color);
    line-height: var(--ck-content-line-height);
    word-break: var(--ck-content-word-break);
}

```

Those content styles are easily replaceable via CSS variable override. It is possible that you already style those things with more specific selectors but we recommend to use the variables from now on.  
You can read more about the reasons in our [GitHub issue](https://github.com/ckeditor/ckeditor5/issues/18710).

**Migration:**

* If you notice that the new editor’s content styling affected your content appearance, make sure to update your custom style sheet, and use the new variable names.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--content-area-css-variables-renamed-to-ck-content-prefix">

#### Content area CSS variables renamed to `--ck-content-*` prefix

To improve consistency, all CSS variables that affect the styles of the editor content area (“content styles”) have been renamed to use the `--ck-content-*` prefix. This change affects variables used for highlights, image captions, mentions, table captions, image style spacing, and to-do list checkmarks.

| Old variable name                           | New variable name                                        |
| ------------------------------------------- | -------------------------------------------------------- |
| \--ck-highlight-marker-yellow               | \--ck-content-highlight-marker-yellow                    |
| \--ck-highlight-marker-green                | \--ck-content-highlight-marker-green                     |
| \--ck-highlight-marker-pink                 | \--ck-content-highlight-marker-pink                      |
| \--ck-highlight-marker-blue                 | \--ck-content-highlight-marker-blue                      |
| \--ck-highlight-pen-red                     | \--ck-content-highlight-pen-red                          |
| \--ck-highlight-pen-green                   | \--ck-content-highlight-pen-green                        |
| \--ck-color-image-caption-background        | \--ck-content-color-image-caption-background             |
| \--ck-color-image-caption-text              | \--ck-content-color-image-caption-text                   |
| \--ck-color-mention-background              | \--ck-content-color-mention-background                   |
| \--ck-color-mention-text                    | \--ck-content-color-mention-text                         |
| \--ck-color-selector-caption-background     | ⚠️ NEW NAME \--ck-content-color-table-caption-background |
| \--ck-color-selector-caption-text           | ⚠️ NEW NAME \--ck-content-color-table-caption-text       |
| \--ck-image-style-spacing                   | \--ck-content-image-style-spacing                        |
| \--ck-inline-image-style-spacing            | \--ck-content-inline-image-style-spacing                 |
| \--ck-todo-list-checkmark-size              | \--ck-content-todo-list-checkmark-size                   |
| \--ck-table-of-contents-padding             | \--ck-content-table-of-contents-padding                  |
| \--ck-table-of-contents-line-height         | \--ck-content-table-of-contents-line-height              |
| \--ck-table-of-contents-items-start-padding | \--ck-content-table-of-contents-items-start-padding      |

**Migration:**

* Update your custom style sheets, themes, and integrations to use the new variable names.
* The old variable names are no longer supported and will not have any effect.

Example:

```
:root {
    --ck-content-highlight-marker-yellow: #fdfd77;
    --ck-content-color-image-caption-background: hsl(0, 0%, 97%);
}

```

<a id="ckeditor5/latest/updating/guides/update-to-46.html--table-related-css-variables-renamed-for-better-clarity">

##### Table-related CSS variables renamed for better clarity

Some table-related CSS variables had improper naming with `-selector-` in their names, which was confusing and inconsistent. These variables have been renamed to use `-table-` for better clarity and consistency.

| Old variable name                                   | New variable name                                |
| --------------------------------------------------- | ------------------------------------------------ |
| \--ck-color-selector-caption-highlighted-background | \--ck-color-table-caption-highlighted-background |
| \--ck-color-selector-column-resizer-hover           | \--ck-color-table-column-resizer-hover           |
| \--ck-color-selector-focused-cell-background        | \--ck-color-table-focused-cell-background        |

**Migration:**

* Update your custom style sheets and themes to use the new variable names.
* The old variable names are no longer supported and will not have any effect.

Example:

```
:root {
    --ck-color-table-caption-highlighted-background: hsl(52deg 100% 50%);
    --ck-color-table-column-resizer-hover: var(--ck-color-base-active);
    --ck-color-table-focused-cell-background: hsla(212, 90%, 80%, .3);
}

```

<a id="ckeditor5/latest/updating/guides/update-to-46.html--multi-level-list-markup-change">

#### Multi-level list markup change

Due to work on fixing the [list markers formatting](https://github.com/ckeditor/ckeditor5/issues/5752), we changed the markup of the Multi-level list feature. This has no visual affect, but may trigger some automated tests issues. **There is no need to migrate content during the update.**

**Before:**

```
<ol class="multi-level-list legal-list" style="list-style-type:none;">
    <li>
        <span class="multi-level-list__marker">1. </span>Foo bar
    </li>
</ol>

```

**After:**

```
<ol class="multi-level-list legal-list" style="list-style-type:none;">
    <li>
        <span class="multi-level-list__marker"><span>1.</span>&nbsp;</span>Foo bar
    </li>
</ol>

```

<a id="ckeditor5/latest/updating/guides/update-to-46.html--list-item-identification-in-editor-data">

#### List item identification in editor data

The `data-list-item-id` attribute is now added to the `<li>` elements in the editor data to improve integration between the list feature and other editor features. This attribute provides a stable identifier for list items that remains consistent across data loads and saves, resolving issues with data stability and improving compatibility with external systems and diffing algorithms.

**Before:**

```
<ul>
        <li>
                <p>First item</p>
                <p>Second paragraph</p>
        </li>
        <li>Another item</li>
</ul>

```

**After:**

```
<ul>
        <li data-list-item-id="abc123">
                <p>First item</p>
                <p>Second paragraph</p>
        </li>
        <li data-list-item-id="def456">Another item</li>
</ul>

```

This change ensures that list items maintain consistent identifiers across editor sessions, improving the reliability of features that depend on list structure tracking. The attribute is automatically generated and maintained by the editor, requiring no action from developers.

If you need to export clean HTML without these IDs (for presentation purposes only), you can use the `skipListItemIds` option when calling `editor.getData()`:

```
// Get data without list item IDs (for presentation only)
const cleanHtml = editor.getData({ skipListItemIds: true });

```

For more technical details, see [GitHub issue #18407](https://github.com/ckeditor/ckeditor5/issues/18407).

<a id="ckeditor5/latest/updating/guides/update-to-46.html--comments-annotation-styles-standardization">

#### Comments annotation styles standardization

The default styles for comments annotations have changed significantly. Previously, the defaults were set only on part of the comments UI, and the comments UI was affected by the main editor content styles. Now, we have introduced a standardized set of CSS variables that are applied to both the comments content and input field.

**New CSS variables introduced:**

* `--ck-comment-content-font-family`
* `--ck-comment-content-font-size`
* `--ck-comment-content-font-color`

These variables have default values based on the editor’s UI styles, which may be different from styles you currently have set. Most notably, the default font color has changed from black `hsl(0, 0%, 0%)` to dark gray `hsl(0, 0%, 20%)` to match the rest of the editor UI.

**Migration:**

1. Review the comments appearance after updating the editor
2. If the new default styles do not match your design requirements, set custom values using the new CSS variables:

```
:root {
    --ck-comment-content-font-family: "Your preferred font family";
    --ck-comment-content-font-size: 14px;
    --ck-comment-content-font-color: hsl(0, 0%, 0%); /* or your preferred color */
}

```

This change ensures consistent styling across all comments-related UI elements and provides better integration with the overall editor design system.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--improved-vertical-spacing-for-paragraphs-in-lists-and-tables">

#### Improved vertical spacing for paragraphs in lists and tables

During the work on Line Height, we changed the behavior how paragraphs behave in lists and table cells. It was [a long-reported bug](https://github.com/ckeditor/ckeditor5/issues/11347) which caused a confusion for writers. We decided to solve it with opinionated content styles, and it may result in a **visual change** of your content after the update. If you are not satisfied with the result, you can revert the change in the CSS:

```
.ck-content li > p:first-of-type {
        margin-top: revert;
    }


.ck-content li > p:only-of-type {
    margin-top: revert;
    margin-bottom: revert;
}

.ck-content table.table:not(.layout-table),
.ck-content figure.table:not(.layout-table) > table {
    > thead,
    > tbody {
        > tr {
            > td,
            > th {
                > p:first-of-type {
                    margin-top: revert;
                }

                > p:last-of-type {
                    margin-bottom: revert;
                }
            }
        }
    }
}

```

<a id="ckeditor5/latest/updating/guides/update-to-46.html--comment-threads-improvements">

#### Comment threads improvements

<a id="ckeditor5/latest/updating/guides/update-to-46.html--new-thread-command-changes">

##### New thread command changes

We have introduced improvements to the `addCommandThread` command, which now supports creating comment threads on specified ranges. Additionally, it allows for creating a comment thread with an initial comment with the provided comment content.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--minor-breaking-change">

###### Minor breaking change

The `AddCommandThreadCommand#isEnabled` property is no longer `false` when the current document selection is empty, as the command now allows for creating comment threads on custom ranges. If you previously used this property (for example, to provide a custom UI element), you should now use the observable `AddCommentThreadCommand#hasContent` property instead.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--comments-and-suggestions-annotations">

##### Comments and suggestions annotations

We have introduced dedicated methods for an easier way to get specific annotations related to a comment or a suggestion and vice versa.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--major-breaking-changes-in-this-release">

#### Major breaking changes in this release

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The AI Assistant now uses the more advanced `gpt-4o` model by default, replacing the previous `gpt-3.5-turbo`. This update improves response quality and overall capabilities. Additionally, the default limit set by `max_tokens` parameter has been removed, allowing for better and more detailed responses. If you relied on the previous default settings and wish to continue using them, be sure to explicitly define the editor configuration entry `ai.openAi.requestParameters` to `{ model: 'gpt-3.5-turbo', max_tokens: 2000, stream: true }`.
* **[document-outline](https://www.npmjs.com/package/@ckeditor/ckeditor5-document-outline)**: Content area CSS variables have been renamed to use the --ck-content-\* prefix for better consistency in the Table of Contents feature. This requires action if you have overridden the variables. See the update guide for details.
* **[list](https://www.npmjs.com/package/@ckeditor/ckeditor5-list)**: Removed vertical spacing in list items by resetting margins for `<p>` elements that are the child of a `<li>` element.
* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table)**: Removed vertical spacing in table cells by collapsing margins of  
 elements that are the only child of a `<td>` or `<th>` element.
* The editor now enforces default browser styles for text content in both the editing view and rendered output. This change may affect existing styling and layout, so any custom CSS overrides should be reviewed. See [#18710](https://github.com/ckeditor/ckeditor5/issues/18710) for details. The following CSS variables and their default values are now applied:

  * `--ck-content-font-family`: `Helvetica, Arial, Tahoma, Verdana, sans-serif`
  * `--ck-content-font-size`: `medium`
  * `--ck-content-font-color`: `#000` (_HEX instead of `hsl()` to ensure compatibility with email clients_)
  * `--ck-content-line-height`: `1.5`
  * `--ck-content-word-break`: `break-word`
* The default styles for comment annotations have changed to provide better consistency with the editor UI. A new set of CSS variables is now used to control the appearance of the comment content and input fields. These changes may affect the current appearance of comments in your integration, so please review them after updating. The following CSS variables are now applied:

  * `--ck-comment-content-font-family`
  * `--ck-comment-content-font-size`
  * `--ck-comment-content-font-color` (default changed from `hsl(0, 0%, 0%)` to `hsl(0, 0%, 20%)`)  
These variables default to values derived from the editor 's UI styles, and they may differ from your current settings. Customize these variables as needed to match your desired appearance.
* Content area CSS variables have been renamed to use the `--ck-content-*` prefix for better consistency in the Highlight, Image, List, and Table features. This requires action if you have overridden the variables. See the update guide for details.
* Table-related CSS variables with improper `*-selector-*` naming have been renamed to use `*-table-*` for better clarity. This requires action if you have overridden the variables. See the update guide for details.

<a id="ckeditor5/latest/updating/guides/update-to-46.html--minor-breaking-changes-in-this-release-2">

#### Minor breaking changes in this release

* **[comments](https://www.npmjs.com/package/@ckeditor/ckeditor5-comments)**: The `AddCommandThreadCommand#isEnabled` property is no longer `false` when the current document selection is empty, as the command now allows for creating comment threads on custom ranges. If you previously used this property (for example, to provide a custom UI element), you should now use the observable `AddCommentThreadCommand#hasContent` property instead.
* **[core](https://www.npmjs.com/package/@ckeditor/ckeditor5-core)**: Removed the deprecated `DataApiMixin` function and `DataApi` interface. Their functionality is the part of the Editor class.
* **[engine](https://www.npmjs.com/package/@ckeditor/ckeditor5-engine)**: Removed `Batch#type` deprecated property.
* **[list](https://www.npmjs.com/package/@ckeditor/ckeditor5-list)**: Removed `DocumentList`, `DocumentListProperties` and `TodoDocumentList` plugins. They were aliases for plugins `List`, `ListProperties` and `DocumentList` respectively.
* **[markdown-gfm](https://www.npmjs.com/package/@ckeditor/ckeditor5-markdown-gfm)**: Migrated from `marked` and `turndown` to `remark` and `rehype` for improved extensibility and alignment with the modern Markdown ecosystem.
* **[markdown-gfm](https://www.npmjs.com/package/@ckeditor/ckeditor5-markdown-gfm)**: Enabled the autolinking feature in Markdown when loading Markdown content into the editor.
* **[ui](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui)**: Removed the deprecated `buttonView` property from buttons created with `FileDialogViewMixin`. Use the button object itself.
* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: Removed the deprecated `mix` function.
* **[utils](https://www.npmjs.com/package/@ckeditor/ckeditor5-utils)**: Removed the deprecated `Locale#language` property. Use `Locale#uiLanguage` instead.ase

<a id="ckeditor5/latest/updating/guides/update-to-47.html">source file: "ckeditor5/latest/updating/guides/update-to-47.html"</a>

## Update to CKEditor 5 v47.x

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4760">

### Update to CKEditor 5 v47.6.0

Released on 4 March, 2026\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.6.0))

<a id="ckeditor5/latest/updating/guides/update-to-47.html--new-htmlsupporthtmliframesandbox-configuration-option-in-general-html-support">

#### New `htmlSupport.htmlIframeSandbox` configuration option in General HTML Support

This release introduces a potential breaking change related to `iframe` handling in the editing view.

By default, iframe sandboxing is now enabled. The `htmlSupport.htmlIframeSandbox` configuration option responsible for this behavior defaults to `true`, which means an empty `sandbox=""` attribute is automatically added to all iframes rendered in the editing view.

Previously, iframes were not sandboxed by default and had full access to the surrounding page context. With this change, iframes are now restricted unless explicitly configured otherwise.

If you want to preserve the previous behavior (unsandboxed iframes with full access), you must explicitly disable this feature by setting the configuration option to `false`.

Besides `true` or `false`, the `htmlSupport.htmlIframeSandbox` configuration option accepts an array of strings. For example, if you want to allow only specific features, set it to `allow-scripts`. In this scenario, we will ensure that `allow-scripts` is the only value in the sandbox attribute. If the iframe already has other sandbox values, they will be removed; if it has no sandbox attribute, we will add `sandbox="allow-scripts"`.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--changes-to-the-srcdoc-attribute-in-the-editing-view">

#### Changes to the `srcdoc` attribute in the editing view

The `srcdoc` attribute is no longer rendered in the editing view.

Unlike iframe sandboxing, this change is permanent and cannot be disabled via configuration. Any iframe content provided through `srcdoc` will be ignored in the editing view going forward.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--new-ordered-list-styles">

#### New ordered list styles

We have introduced a new ordered list style: the `arabic-indic` numerals. To use them, you need to explicitly activate the style in the [feature configuration](#ckeditor5/latest/features/lists/lists.html--enabling-specific-enumerators).

The same style is also available in the [footnotes](#ckeditor5/latest/features/footnotes.html--the-footnotesproperties-contextual-balloon) feature for numbering footnote markers.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--visual-block-indentation-for-lists">

#### Visual block indentation for lists

The block indentation feature now supports applying visual indentation to list containers and list items. When the `Indent`, `IndentBlock`, and `List` plugins are all loaded, you can indent top-level lists using the toolbar buttons or keyboard shortcuts. The editor also recognizes `margin-left` styles on `<ol>`, `<ul>`, and `<li>` elements during data loading. See the [Indenting lists](#ckeditor5/latest/features/indent.html--indenting-lists) documentation for details.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--mirror-margins-in-export-to-pdf-v2">

#### Mirror margins in Export to PDF V2

The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature now supports [mirror margins](#ckeditor5/latest/features/converters/export-pdf.html--mirror-margins) for book-like layouts. When enabled, left and right margins are treated as inner and outer margins that swap between odd and even pages, making it easy to prepare documents for double-sided printing or binding.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--preserving-the-figure-wrapper-for-content-tables">

#### Preserving the `<figure>` wrapper for content tables

When using content tables together with layout tables, the `<figure>` element is stripped from tables in both cases by default. This version introduces a new flag [stripFigureFromContentTable](../../api/module%5Ftable%5Ftableconfig-TableLayoutConfig.html#member-stripFigureFromContentTable) which allows to change the behavior and preserve the `<figure>` element.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ckeditor-ai-on-premises">

#### CKEditor AI On-premises

[CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html) is now available as an **on-premises deployment**, giving you full control over the AI service by running it on your infrastructure. The on-premises version supports everything the cloud option offers, plus:

* **Custom AI models and providers** – use your models from OpenAI, Google Cloud, Microsoft Azure, or self-hosted solutions.
* **MCP (Model Context Protocol) support** – extend the AI with custom external tools by connecting MCP servers, enabling use cases like searching internal knowledge bases or querying company databases directly from the AI chat.

Learn more about [deployment options](#ckeditor5/latest/features/ai/ckeditor-ai-deployment.html) and [MCP support](#ckeditor5/latest/features/ai/ckeditor-ai-mcp.html).

<a id="ckeditor5/latest/updating/guides/update-to-47.html--custom-ai-review-checks">

#### Custom AI Review checks

The [AI Review](#ckeditor5/latest/features/ai/ckeditor-ai-review.html) feature now supports **custom review commands** defined by integrators. Until now, the review was limited to built-in commands like proofreading, clarity, readability, and tone adjustment. With this release, you can create review commands tailored to your editorial guidelines, brand voice, or domain-specific quality standards.

Custom commands are registered via `config.ai.review.extraCommands` and made visible in the UI through `config.ai.review.availableCommands`. The same option lets you reorder, filter, or shorten the list of built-in commands to match your needs. See the [AI Review documentation](#ckeditor5/latest/features/ai/ckeditor-ai-review.html) for details.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ai-chat-shortcuts">

#### AI Chat Shortcuts

We are introducing **AI Chat Shortcuts**, a new opt-in plugin that displays configurable shortcut buttons in the [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) panel before the first message is sent. Shortcuts provide clear, actionable entry points that guide users toward the most useful AI capabilities – from launching a predefined prompt to starting a specific review or translation flow to navigating directly to the Review or Translate tab.

Integrators define shortcuts with a name, icon, and an action. Each shortcut can also configure which AI capabilities (model, web search, reasoning) are active for the prompt. Learn more in the [AI Chat Shortcuts documentation](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--chat-shortcuts).

<a id="ckeditor5/latest/updating/guides/update-to-47.html--upgrade-aws-sdkclient-bedrock-runtime-to-the-latest-version">

#### Upgrade `@aws-sdk/client-bedrock-runtime` to the latest version

We upgraded `@aws-sdk/client-bedrock-runtime` to the latest version to address a recently disclosed security vulnerability in the `fast-xml-parser` dependency. This update is marked as a minor breaking change due to the use of dynamic imports in one of the underlying packages, which may impact certain build environments.

If you use `webpack` to build an editor bundle, configure it to bundle dynamic imports eagerly:

```
module: {
    parser: {
        javascript: {
            dynamicImportMode: 'eager'
        }
    }
}

```

If you do not use CKEditor AI with a dedicated bundle, no action is required.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--minor-breaking-changes-in-this-release">

#### Minor breaking changes in this release

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Simplified the default greeting message shown when starting a new AI Chat conversation. To restore the previous message content, set `config.ai.chat.welcomeMessage` to the following:  
“Hi, I’m your AI assistant. Think of me as your writing buddy, reviewer, or research partner. I can suggest changes to your document, help generate ideas, offer feedback, discuss attached files, and much more!”
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Updated `@aws-sdk/client-bedrock-runtime` to version `3.994.0`. This update introduced dynamic imports in a dependency, which may affect some build environments.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4750">

### Update to CKEditor 5 v47.5.0

Released on 11 February, 2026\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.5.0))

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ai-translate">

#### AI Translate

The [AI Translate feature](#ckeditor5/latest/features/ai/ckeditor-ai-translate.html) of CKEditor AI allows users to translate entire documents on the go. It provides a user interface similar to AI Review, but with translation-specific actions to streamline the process. The translation view displays the final translated document, with original snippets shown on the side for review and comparison.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--visual-changes-to-the-ai-chat-feed">

#### Visual changes to the AI Chat feed

The DOM structure of the [CKEditor AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) suggestions in conversation has changed, which may affect integrations that customized the UI and rely on specific CSS selectors.

Please make sure to update your integrations to use the new DOM structure.

Notable changes:

* “Apply all” and “Suggest all” buttons are now separate buttons instead of a dropdown.
* The toolbar with bulk “Apply” and “Suggest” (“Apply all” and “Suggest all”) buttons belongs to the `.ck-ai-suggestion__body` element (previously in `.ck-ai-chat__feed__item`).
* The `.ck-ai-suggestion__body__content-part__content` has been replaced by `.ck-content.ck-ai-suggestion-streamable-content`.

**Old DOM structure**

```
div.ck-ai-chat__feed__item.ck-ai-chat__feed__ai-suggestion
├── div.ck-ai-suggestion__container.ck-rounded-corners
│   ├── div.ck-ai-suggestion__header
│   │   ├── span ("Change N" label)
│   │   └── button.ck-button.ck-ai-suggestion__header__show-changes-toggle
│   └── div.ck-ai-suggestion__body
│       └── div.ck-ai-suggestion__body__content-parts
│           ├── div.ck-ai-suggestion__body__content-part.ck-ai-suggestion__body__content-part_pending
│           │   ├── div.ck-ai-suggestion__body__content-part__title
│           │   │   ├── span.ck-ai-suggestion__body__content-part__title__label
│           │   │   └── div.ck-toolbar
│           │   │       └── div.ck-toolbar__items (Toolbar with "Preview", "Insert as suggestion", "Reject" buttons)
│           │   │           ├── button.ck-button
│           │   │           └── ...
│           │   └── div.ck-content.ck-ai-suggestion__body__content-part__content
│           │       └── (Content of the suggestion part)
│           └── ... Other changes suggested by the AI ...
└── div.ck-ai-chat__feed__ai-suggestion__actions
    └── div.ck-splitbutton.ck-ai-chat__feed__ai-suggestion__actions (Dropdown with "Apply all", bulk "Suggest", and "Preview" buttons)
        ├── button.ck-button.ck-splitbutton__action
        └── button.ck-button.ck-splitbutton__arrow

```

**New DOM structure**

```
div.ck-ai-chat__feed__item.ck-ai-chat__feed__ai-suggestion
└── div.ck-ai-suggestion__container.ck-rounded-corners
    ├── div.ck-ai-suggestion__header
    │   ├── span ("Suggestion N" label)
    │   └── button.ck-button.ck-ai-suggestion__header__show-changes-toggle
    └── div.ck-ai-suggestion__body
        ├── div.ck-ai-suggestion__body__content-parts
        │   ├── div.ck-ai-suggestion__body__content-part.ck-ai-suggestion__body__content-part_pending
        │   │   ├── div.ck-ai-suggestion__body__content-part__title
        │   │   │   ├── span.ck-ai-suggestion__body__content-part__title__label
        │   │   │   └── div.ck-toolbar.ck-ai-suggestion-content-part-toolbar
        │   │   │       └── div.ck-toolbar__items (Toolbar with "Apply change", "Add as suggestion", and "Reject change" buttons)
        │   │   │           ├── button.ck-button
        │   │   │           └── ...
        │   │   └── div.ck-content.ck-ai-suggestion-streamable-content
        │   │       └── (Content of the suggestion part)
        │   └── ... Other changes suggested by the AI ...
        └── div.ck-ai-chat__feed__ai-suggestion__actions (Separate buttons for bulk "Apply" and "Suggest")
            ├── button.ck-button.ck-ai-button-primary
            └── button.ck-button.ck-ai-button-secondary

```

<a id="ckeditor5/latest/updating/guides/update-to-47.html--visual-changes-to-the-ai-chat-suggestion-preview-dialog-window">

#### Visual changes to the AI Chat suggestion preview dialog window

The DOM structure of the [CKEditor AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) suggestion [preview dialog window](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--previewing-changes) has changed, which may affect integrations that customized the UI and/or rely on specific CSS selectors.

Please make sure to update your integrations to use the new DOM structure.

**Old DOM structure**

```
div.ck-dialog.ai-balloon.ai-balloon-rotator
├── div.ck-form__header
│   ├── button.ck-button.ck-off (Previous suggestion button)
│   ├── h2.ck-form__header__label (Suggestion title)
│   ├── button.ck-button.ck-off (Next suggestion button)
│   └── button.ck-button.ck-off (Close button)
└── div.ck-dialog__content
    └── div.ai-balloon-content
        ├── div.ck-ai-suggestion__container.ck-rounded-corners
        │   └── div.ck-ai-suggestion__body
        │       ├── div.ck-ai-suggestion__body__content-parts
        │       │   └── div.ck-ai-suggestion__body__content-part.ck-ai-suggestion__body__content-part_pending.ck-ai-suggestion__body__content-part_active
        │       │       └── div.ck-content.ck-ai-suggestion__body__content-part__content
        │       │           └── (Content of the suggestion)
        │       └── div.ck-toolbar.ck-ai-mini-toolbar
        │           └── div.ck-toolbar__items
        │               └── button.ck-button (Show changes button)
        ├── div.ck-ai-balloon__disclaimer
        │   └── p.ck-ai-balloon__disclaimer-content
        └── div.ck-toolbar.ck-ai-balloon__toolbar
            └── div.ck-toolbar__items
                ├── button.ck-button.ck-ai-button-primary ("Apply" button)
                └── button.ck-button.ck-ai-button-secondary ("Suggest" button)

```

**New DOM structure**

```
div.ck-dialog.ck-ai-balloon.ck-ai-chat-balloon
├── div.ck-form__header
│   ├── button.ck-button.ck-off (Previous suggestion button)
│   ├── button.ck-button.ck-off (Next suggestion button)
│   ├── h2.ck-form__header__label (Suggestion title)
│   └── button.ck-button.ck-off (Close button)
└── div.ck-dialog__content
    └── div.ck-ai-chat-balloon-main.ck-ai-chat-balloon-main_state_pending
        ├── div.ck-content.ck-ai-suggestion-streamable-content
        │   └── (Content of the suggestion)
        └── div.ck-ai-chat-balloon__toolbar-container
            ├── div.ck-toolbar.ck-ai-suggestion-content-part-toolbar
            │   └── div.ck-toolbar__items
            │       ├── button.ck-button ("Apply change" button)
            │       ├── button.ck-button ("Add as suggestion" button)
            │       └── button.ck-button ("Reject change" button)
            ├── div.ck-ai-suggestion__content-part-state.ck-ai-suggestion__content-part-state_pending.ck-hidden
            │   └── span.ck-ai-suggestion__content-part-state__label
            └── div.ck-toolbar.ck-ai-mini-toolbar
                └── div.ck-toolbar__items
                    └── button.ck-button ("Show changes" button)

```

<a id="ckeditor5/latest/updating/guides/update-to-47.html--multiple-changes-revamp-and-other-ai-improvements">

#### Multiple Changes revamp and other AI improvements

We improved how multiple changes proposed by the [AI Chat](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html) feature are presented. Suggested changes now appear as cards that can be previewed in the content and applied consistently in both single-change and multi-change scenarios. This release also includes several under-the-hood improvements.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--export-to-pdf-v2">

#### Export to PDF v2

The [export to PDF](#ckeditor5/latest/features/converters/export-pdf.html) feature now supports version 2 of the HTML to PDF converter API, bringing several [powerful enhancements](#ckeditor5/latest/features/converters/export-pdf.html--html-to-pdf-converter-features) to document generation.

Advanced header and footer configurations allow for different content on first, odd, and even pages, with support for images. Page sizes can now be set using predefined formats or custom width and height values. The new converter API also enables editing of PDF metadata fields such as title, subject, and author.

Security capabilities have been expanded with owner password protection for controlling permissions and digital signature support using PKCS#12 certificates for authenticity verification. Additional improvements include compression control for specific use cases and more precise rendering options.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--incoming-old-installation-methods-sunset-reminder">

#### Incoming old installation methods sunset reminder

Please note that the old installation methods will no longer be available with CKEditor 5 v48.0.0, which is planned for release at the beginning of Q2 2026\. For more timeline details, refer to the [dedicated GitHub issue](https://github.com/ckeditor/ckeditor5/issues/17779).

In CKEditor 5 v42.0.0 in June 2024, we [introduced new installation methods](https://ckeditor.com/blog/ckeditor-5-new-era-installation-simplicity/) designed to improve and simplify the developer workflow. Soon, they will be the only available paths to install and use CKEditor 5.

If your project still relies on old installation methods, now is a good time to plan your next steps. We recommend choosing between these two options:

1. [Migrate to the new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html), which are the recommended path for most users. The new installation methods provide a cleaner setup, easier upgrades, and better alignment with future CKEditor 5 releases.
2. Consider [CKEditor 5 Long-Term Support (LTS)](https://ckeditor.com/ckeditor-5-lts/). If migrating in the near term is not feasible, you can extend support for legacy installation methods.

Please refer to the [update guide](#ckeditor5/latest/updating/guides/update-to-42.html) to learn more about these changes.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--minor-breaking-changes-in-this-release-2">

#### Minor breaking changes in this release

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The `ai.reviewMode.translations` configuration option has been moved to `ai.translate.languages`. The `ai.reviewMode` configuration namespace has been removed.  
Together with the introduction of AI Translate feature and a separate translation tab, the configuration option to define a custom language list  
has been moved to a related `ai.translate` namespace.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The `AIEditorIntegration` plugin is now required to preview the changes suggested by the AI Chat feature in a dialog window. Previously, this functionality was enabled by just loading the main `AIChat` plugin. Please make sure your integration loads the `AIEditorIntegration` plugin in order to use this functionality.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The DOM structure of the AI Chat suggestions in conversation has been changed, which may affect integrations that customized the UI and/or rely on specific CSS selectors.  
Please make sure to update your integrations to use the new DOM structure. Learn more about the changes in the migration guide provided in the project documentation.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The DOM structure of the AI Chat suggestion preview dialog window has been changed which may affect integrations that customized the UI and/or rely on specific CSS selectors.  
Please make sure to update your integrations to use the new DOM structure. Learn more about the changes in the migration guide provided in the project documentation.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: `AIChat#sendMessage()` takes `attributes: Record<string, unknown>` as one of its parameters now, in place of former `quickActionData`. This affects you only if you provided some customizations for the CKEditor AI chat feature.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Already existing chat conversations, which were created through AI Quick Action (e.g. “Explain” or “Summarize”), when loaded from chat history, will now display a full prompt instead of the short version. This affects only already created conversations.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Replaced `ai.chat.models.modelSelectorAlwaysVisible` configuration option with `ai.chat.models.showModelSelector`. The behavior has also been slightly updated. When set to `true` (default), the model selector dropdown is shown (when multiple models are available), or the model name is displayed (when only one model is available). When set to `false`, the selector is hidden, regardless of the number of available models.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The model’s configuration options have been moved from `config.ai.chat.models` to `config.ai.models` to ensure consistent model configuration across all AI features. The model configuration is now applied uniformly in both AI Chat and AI Review Mode.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4740">

### Update to CKEditor 5 v47.4.0

Released on 14 January, 2026\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.4.0))

This is a minor update focused on improving content editing workflows and data compatibility. We are introducing better visualization for table borders, enhanced image alignment handling, and several improvements to AI and email features.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--experimental-table-cell-type-support">

#### Experimental table cell type support

We are introducing an experimental [tableCellTypeSupport](../../api/module%5Ftable%5Ftablecellproperties%5Ftablecellpropertiesutils-TableCellType.html) flag that enables changing table cell types between data and header cells (`th`). This feature provides more flexibility when working with complex table structures. To enable this functionality, you need to set `experimentalFlags.tableCellTypeSupport` to `true`. You can then use `TableCellPropertiesEditing` and `TableCellPropertiesUIExperimental` to manage the feature.

```
 ClassicEditor
     .create( document.querySelector( '#editor' ), {
        plugins: [
            Essentials,
            Paragraph,
            Table,
-            TableProperties,
-            TableCellProperties
+            TablePropertiesEditing,
+            TablePropertiesUIExperimental,
+            TableCellPropertiesEditing,
+            TableCellPropertiesUIExperimental
        ],
        experimentalFlags: {
            // ... other experimental flags ...
+            tableCellTypeSupport: true
        }
     } )
     .then( /* ... */ )
     .catch( /* ... */ );

```

The fully functional editor UI for cell type support will be available with the next major CKEditor 5 version.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--hidden-table-borders-visualization">

#### Hidden table borders visualization

We are introducing a new [config.table.showHiddenBorders](#ckeditor5/latest/features/tables/tables-styling.html--helper-lines-when-border-style-is-set-to-none) configuration option (enabled by default) that helps editors work with tables that have hidden borders. When the editor detects inline `border:none` or `border-style:none` declarations on table and cell elements, it renders dashed helper borders in the editing view. This makes it easier to see the table structure while editing without affecting the output data. This visualization can be disabled for strict WYSIWYG scenarios where you want the editing view to match the output exactly.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--email-compatibility-improvements">

#### Email compatibility improvements

We improved the [email styles transformation](#ckeditor5/latest/features/email-editing/email.html--email-specific-style-transformations) with better appearance of resized inline images in classic Outlook clients. Additionally, the new optional `useFigureToTableFallback` flag in the email styles transformers can replace `figure` (block images) with tables to improve alignment and width handling in older email clients with limited CSS support.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--updated-the-emoji-plugin-dataset">

#### Updated the Emoji plugin dataset

The Emoji plugin can now utilize the Emoji v17.0 dataset, available on the CKEditor CDN. This update does not change the default emoji version used by CKEditor 5.

To use the new dataset, download the [Emoji json database from the CKEditor 5 CDN](https://cdn.ckeditor.com/ckeditor5/data/emoji/17/en.json). Place the downloaded file in your application’s assets folder, for example `public/emoji/en.json` (The specific location may vary depending on your framework and setup). Update the configuration option `definitionsUrl` to point to the URL of your assets, for example:

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Other configuration options ...
        emoji: {
            definitionsUrl: 'https://example.com/emoji-definitions.json'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/updating/guides/update-to-47.html--other-improvements-and-fixes">

#### Other improvements and fixes

* Fixed multiple issues in the AI features, including improved tooltips for web search sources in AI Chat, proper handling of Quick Actions when opening the AI Chat panel, resolved loading state issues in the AI Review sidebar, and others.
* The editor now recognizes CSS `float` style on images (e.g., `style="float: left"` or `style="float: right"`) and automatically maps it to left/right image alignment. This works for both inline and block images, improving compatibility when pasting content from external sources or loading legacy content. If custom image styles are configured, they take precedence over the float style.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--incoming-old-installation-methods-sunset-reminder-2">

#### Incoming old installation methods sunset reminder

Please note that the old installation methods will only remain available up to CKEditor 5 v48.0.0, which is planned for release at the beginning of Q2 2026\. For more timeline details, refer to the [dedicated GitHub issue](https://github.com/ckeditor/ckeditor5/issues/17779).

In CKEditor 5 v42.0.0 in June 2024, we [introduced new installation methods](https://ckeditor.com/blog/ckeditor-5-new-era-installation-simplicity/) designed to improve and simplify the developer workflow. Soon, they will be the only available paths to install and use CKEditor 5.

If your project still relies on old installation methods, now is a good time to plan your next steps. We recommend choosing between these two options:

1. [Migrate to the new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html), which are the recommended path for most users. The new installation methods provide a cleaner setup, easier upgrades, and better alignment with future CKEditor 5 releases.
2. Consider [CKEditor 5 Long Term Support (LTS)](https://ckeditor.com/ckeditor-5-lts/). If migrating in the near term is not feasible, you can extend support for legacy installation methods.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4730">

### Update to CKEditor 5 v47.3.0

Released on 3 December, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.3.0))

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ckeditor-ai-improvements-and-bug-fixes">

#### CKEditor AI improvements and bug fixes

Finding a specific AI Quick Action in a long list with multiple groups can be difficult. To improve this, we are adding a filter input that lets users search for quick actions directly within the dropdown.

Visibility of the input can be easily configured using the `config.ai.quickActions.isSearchEnabled` configuration option.

This release also brings several minor but significant enhancements and fixes:

* Track Changes markers not related to AI suggestions are now displayed in gray in the AI balloon text preview, consistent with the behavior of AI chat.
* When retrying a specific AI Review, we are now ensuring the latest version of the document is used.
* We also improved error handling across CKEditor AI, making it easier to debug backend-related issues by including more detailed error messages.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--new-experimental-options">

#### New experimental options

We keep our [LTS version](#ckeditor5/latest/getting-started/setup/using-lts-edition.html--compatibility-matrix) promise: no breaking changes until the Active LTS moves to Maintenance LTS phase (April 2026). It also means that introducing larger features can be challenging if someone is waiting for specific improvements.

To address this, we are introducing **experimental flags** and **experimental plugins**. These options allow you to preview and test upcoming changes.

* **New table alignment options**  
Enable `config.experimentalFlags.useExtendedTableBlockAlignment` and load the experimental UI plugins `TablePropertiesUIExperimental` and `TableCellPropertiesUIExperimental` for upcoming improvements to table block alignment.  
The `TableProperties` and `TableCellProperties` plugins already include their standard UI counterparts (`TablePropertiesUI` and `TableCellPropertiesUI`). To avoid conflicts, when using experimental UI plugins, you must load the editing plugins (`TablePropertiesEditing`, `TableCellPropertiesEditing`) and the experimental UI plugins separately, instead of using the “glue” plugins.  
New options allow setting left and right table block alignment without text wrapping and resolve issues such as [#3225](https://github.com/ckeditor/ckeditor5/issues/3225). We also improved table properties and cell properties balloon interfaces. This change will be the default in version 48.0.0.
* **Improved table border normalization**  
Setting `config.experimentalFlags.upcastTableBorderZeroAttributes` enables support for the normalization of HTML tables that use `border="0"`. This change will be the default in version 48.0.0.
* **Better deep schema validation**  
After enabling the `config.experimentalFlags.modelInsertContentDeepSchemaVerification` flag, the editor performs deep schema verification during `model.insertContent()` operations. This ensures that the inserted content fully follows the editor’s schema, even in complex or nested structures. This change will be the default in version 48.0.0.
* **Configuration**

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [
            Table,
            TablePropertiesEditing,
            TableCellPropertiesEditing,
            TablePropertiesUIExperimental,
            TableCellPropertiesUIExperimental,
            // Other plugins.
            // ...
        ],
        experimentalFlags: {
            useExtendedTableBlockAlignment: true,
            upcastTableBorderZeroAttributes: true,
            modelInsertContentDeepSchemaVerification: true
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4720">

### Update to CKEditor 5 v47.2.0

Released on 5 November, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.2.0))

This release introduces expanded CKEditor AI feature, new Footnotes features and several improvements.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ckeditor-ai">

#### CKEditor AI

We are introducing [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html), a powerful writing assistant that brings AI-powered content creation directly into CKEditor 5\. It helps users create, review, and refine content without switching between tools, making the editing experience faster and more productive.

CKEditor AI includes three core capabilities:

* **Chat**: a conversational AI assistant for multi-turn interactions that supports context setting and model selection. All conversations are tracked in a persistent chat history, and suggestions are reviewable before being applied.
* **Quick actions**: one-click transformations for selected text, including rewriting, simplifying, expanding, summarizing, or adjusting tone. Changes appear inline with preview capabilities.
* **Review**: automatic quality assurance that checks grammar, tone, clarity, and style across the document. Suggested changes are presented in a visual review interface where users can accept or reject individual edits or apply all approved suggestions in bulk.

Power users can select their preferred model during sessions (GPT-5, Claude 3.5, Gemini 2.5, and more), while integrators maintain control over access rules and usage tiers.

Built as a plugin for CKEditor 5, it integrates quickly into existing applications with minimal configuration, and all AI interactions are fully observable via audit logs and optional APIs.

CKEditor AI is available as a premium add-on to all paid CKEditor 5 plans with a transparent subscription-plus-usage pricing model. A 14-day trial is available with access to all premium features.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--footnotes">

#### Footnotes (⭐)

A brand-new [Footnotes](#ckeditor5/latest/features/footnotes.html) feature is here! It lets users insert and manage footnotes directly in their content, keeping references organized and readable. Footnotes stay linked to their source text and update automatically when edited, ideal for academic, legal, or technical writing. You can also **customize the numbering**, including the starting number and numbering style, to match your document’s formatting needs.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--restricted-editing-for-blocks">

#### Restricted editing for blocks (⭐)

[Restricted editing](#ckeditor5/latest/features/restricted-editing.html) now supports **block-level restrictions**, not just inline ones. This makes it easier to protect the entire content while still allowing controlled edits where required. A common use case is unlocking for editing template sections like paragraphs, tables, or structured document parts, and protecting the rest of the content.  
to do

<a id="ckeditor5/latest/updating/guides/update-to-47.html--legacy-toolbar-button-for-restricted-editing">

##### Legacy toolbar button for restricted editing

The version introduces new toolbar items for the [restricted editing](#ckeditor5/latest/features/restricted-editing.html) feature. The new available toolbar ites are `restrictedEditingException:dropdown` (for both inline and block types of editing fields), `restrictedEditingException:inline`, and `restrictedEditingException:block`.

To retain full backwards compatibility, we have provided an alias toolbar item: `restrictedEditingException`. It is the old toolbar button call and it defaults to inline restricted editing field button. There is no need to change your configuration if you only want to use inline fields type. If you want to use both the block and inline type fields, please [update your toolbar configuration](#ckeditor5/latest/features/restricted-editing.html--configuring-the-toolbar).

<a id="ckeditor5/latest/updating/guides/update-to-47.html--old-installation-methods-sunset-timelines">

#### Old installation methods sunset timelines

We are extending the sunset period for old installation methods ([#17779](https://github.com/ckeditor/ckeditor5/issues/17779)) to the **end of Q1 2026**. It is a good moment to consider switching to the [LTS edition](#ckeditor5/latest/getting-started/setup/using-lts-edition.html) for long-term stability and an additional 3 years of support for the old installation methods.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--other-improvements-and-fixes-2">

#### Other improvements and fixes

This release also brings several smaller but important enhancements and fixes:

* **View engine stability:** Fixed a bug where placeholders could remain visible after view changes, such as moving or replacing elements.
* **Downcast reliability:** The [elementToStructure](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fconversion%5Fdowncasthelpers-DowncastHelpers.html#function-elementToStructure) helper now handles nested structures and list elements more consistently, ensuring correct reconversion and structure maintenance.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4710">

### Update to CKEditor 5 v47.1.0

Released on 16 October, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.1.0))

This release introduces a minor stability update, featuring focused fixes and UX improvements.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--minor-breaking-changes-in-this-release-3">

#### Minor breaking changes in this release

* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: Simplified CSS for the CKEditor AI integration in a sidebar mode (`config.ai.container.type: 'sidebar'`) by removing default layout constraints:

  * Removed the default `min-height` from `.ck-ai-chat`,
  * Removed the default `height` from `.ck-tabs`,
  * Removed the default `width` from `.ck-ai-tabs`.  
Also, the `--ck-tabs-panels-container-width` custom property has been removed from the codebase.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--update-to-ckeditor-5-v4700">

### Update to CKEditor 5 v47.0.0

Released on 1 October, 2025\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v47.0.0))

<a id="ckeditor5/latest/updating/guides/update-to-47.html--ckeditor-ai-early-access">

#### CKEditor AI (early access)

We are introducing [**CKEditor AI**](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html), a set of versatile AI-powered features that integrate directly into CKEditor 5\. It brings generation, summarization, correction, contextual chat help, reviews, and many other capabilities, right into the editor. With **CKEditor AI**, users will no longer need to switch between the editor and AI tools.

Three features are available in this early access phase:

* **Chat:** a conversational AI for dynamic, multi-turn interactions that support various context sources, model selection, which can perform changes directly on the document.
* **Quick actions:** one-click transformations and instant insights for selected text.
* **Review:** automatic checks for grammar, tone, correctness, style, and more, with UX optimized for performing full-document review.

Each feature is powered by our state-of-the-art AI service, available in the Cloud today and coming soon for on-premises deployments. This makes CKEditor AI a true plug-and-play solution that works out of the box, eliminating the need for months of custom development.

CKEditor AI is available as part of our **free trial** in early access.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--long-term-support">

#### Long-term Support (⭐)

We are introducing the **CKEditor 5 LTS (Long-term Support) Edition**, giving teams up to 3 years of stability with guaranteed updates.

The first LTS release is **v47.0.0** (October 2025). It will receive **6 months of active development** with new features and fixes, then **2.5 years of maintenance** with security and critical compatibility updates.

For **v47.x**, the Maintenance phase starts in **April 2026**. From then the next versions in the v47.x line will be available only under a **commercial LTS Edition license**. Therefore, starting in April, integrators without an LTS license should migrate to v48.x (the next regular release).

If you need long-term stability, [contact sales](https://ckeditor.com/contact-sales/) or read more about the [CKEditor 5 LTS Edition](#ckeditor5/latest/getting-started/setup/using-lts-edition.html).

<a id="ckeditor5/latest/updating/guides/update-to-47.html--updated-content-navigation-with-kbdtabkbd-kbdshiftkbdkbdtabkbd">

#### Updated content navigation with Tab / Shift+Tab

Starting with version **v41.3.0**, we have disabled the default browser tab behavior for cycling nested editable elements inside the editor. Read more about it in the `#updated-keyboard-navigation` section of `Update to 41.x` in [updating from older versions guide](#ckeditor5/latest/updating/guides/updating-from-older-versions.html). We decided back then that the Tab (and Shift+Tab) keystroke should navigate to the next focusable field or element outside the editor so the users can quickly navigate fields or links on the page.

There was one exception to this Tab behavior, however. When a user selected a widget, the Tab key would move the selection to the first nested editable, such as the caption of an image. Pressing the Esc key while inside a nested editable will move the selection to the closest ancestor widget, for example, moving from an image caption to selecting the whole image widget.

The above exception was limited as it supported only the first nested editable in a widget (the table widget was an exception that had custom Tab support implemented).

The current release extends the Tab (and Shift+Tab) handling to include all nested editable areas in the editor content. It also includes the content between block widgets as a separate editable area. Thanks to this, the original behavior of jumping away from the editor while pressing Tab inside an image caption is now tuned to jump just after that image. This way, the flow of Tab behavior is more linear and predictable to the user. Also, the custom widgets with multiple nested editable elements are now handled out of the box and require no custom code for Tab handling.

Please make sure that if you had a custom Tab handling implementation in your editor, it does not collide with the default one. Note that generic Tab (and Shift+Tab) handlers are registered on the `low` priority bubbling event in the `context` of widgets and editable elements. For more details on bubbling events and contexts, please see the [bubbling events](#ckeditor5/latest/framework/deep-dive/event-system.html--listening-to-bubbling-events) guide.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--bubbling-events-priorities-fix">

#### Bubbling events priorities fix

The [bubbling events](#ckeditor5/latest/framework/deep-dive/event-system.html--listening-to-bubbling-events) now trigger all event handlers according to the registered priorities, even if multiple custom callback contexts are provided. Previously, not all custom callback contexts were evaluated for a given element. The custom callback contexts were also triggered after the view element name handlers. Now those are all triggered according to the registered priority, regardless of context: element name-based or callback-based.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--other-improvements-and-fixes-3">

#### Other improvements and fixes

This release also brings several smaller but important enhancements and fixes:

* **UI:** dialogs in custom features can now be positioned programmatically with more flexible options (`Dialog#show()`).
* **Comments:** confirmation views for deleting comments and threads now use simplified CSS selectors (`.ck-confirm-view`). You may need to adjust custom styles accordingly.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--major-breaking-changes-in-this-release">

#### Major breaking changes in this release

With the release of [**CKEditor AI**](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html), the `ai.*` configuration structure has changed. Until now, the configuration object was used for the former `AIAssistant` feature.

Now, this configuration space is used for all AI related features. Configuration for the `AIAssistant` was moved. The changes are:  
\* `ai.aiAssistant` \-> `ai.assistant`,  
\* `ai.useTheme` \-> `ai.assistant.useTheme`,  
\* `ai.aws` \-> `ai.assistant.adapter.aws`,  
\* `ai.openAI` \-> `ai.assistant.adapter.openAI`.

<a id="ckeditor5/latest/updating/guides/update-to-47.html--minor-breaking-changes-in-this-release-4">

#### Minor breaking changes in this release

* **[table](https://www.npmjs.com/package/@ckeditor/ckeditor5-table), [widget](https://www.npmjs.com/package/@ckeditor/ckeditor5-widget)**: The Widget feature implements the default handling for `Tab`/`Shift+Tab` to navigate nested editable elements in the editor content. Closes [#19083](https://github.com/ckeditor/ckeditor5/issues/19083). The listeners are registered on the `low` priority bubbling event in the context of widgets and editable elements.  
Please verify if your custom `Tab`/`Shift+Tab` handling does not collide with the default one.
* **[ai](https://www.npmjs.com/package/@ckeditor/ckeditor5-ai)**: The internal structure of the package has changed. Importing `AIAssistant` from the source should be done via `@ckeditor/ckeditor5-ai/src/aiassistant/aiassistant.js` path instead of the previous `@ckeditor/ckeditor5-ai/src/aiassistant.js`.
* **[comments](https://www.npmjs.com/package/@ckeditor/ckeditor5-comments)**: Changed the CSS selectors used to style the confirmation view displayed when attempting to remove a comment or an entire comment thread. For now, CSS classes will be more generic, for example: `.ck-confirm-view` instead of `.ck-thread__remove-confirm`. If you override styles for these components, you will need to update the selectors.
* **[undo](https://www.npmjs.com/package/@ckeditor/ckeditor5-undo)**: The `UndoCommandRevertEvent` type was renamed to `UndoRedoBaseCommandRevertEvent` and moved to the `basecommand.ts` file. Adjust your code if you have used this type in your custom integration. See [#19168](https://github.com/ckeditor/ckeditor5/issues/19168).
* Updated to TypeScript 5.3.

<a id="ckeditor5/latest/updating/guides/update-to-48.html">source file: "ckeditor5/latest/updating/guides/update-to-48.html"</a>

## Update to CKEditor 5 v48.x

<a id="ckeditor5/latest/updating/guides/update-to-48.html--update-to-ckeditor-5-v4800">

### Update to CKEditor 5 v48.0.0

Released on 31 March, 2026\. ([See full release notes](https://github.com/ckeditor/ckeditor5/releases/tag/v48.0.0))

<a id="ckeditor5/latest/updating/guides/update-to-48.html--sunset-of-old-installation-methods-oim">

#### Sunset of old installation methods (OIM)

Starting with v48.0.0, the old installation methods are officially sunset. The related setup guides were removed from regular documentation sections. The legacy setup guides remain available in the CKEditor 5 LTS documentation for users who stay on the LTS line. The migration documentation remains available in the “Updating” category:

* [Migration to new installation methods overview](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html)
* [Migrating from predefined builds](#ckeditor5/latest/updating/nim-migration/predefined-builds.html)
* [Migrating from customized builds](#ckeditor5/latest/updating/nim-migration/customized-builds.html)
* [Migrating from DLL builds](#ckeditor5/latest/updating/nim-migration/dll-builds.html)
* [Migrating from legacy Online Builder](#ckeditor5/latest/updating/nim-migration/online-builder.html)

<a id="ckeditor5/latest/updating/guides/update-to-48.html--root-configuration-migration-and-deprecated-top-level-options">

#### Root configuration migration and deprecated top-level options

The root configuration has been normalized under `config.root` (single-root editors) and `config.roots` (multi-root editors).

The following top-level options are **deprecated**:

* `config.initialData`
* `config.placeholder`
* `config.label`

Additionally, the `sourceElementOrData` parameter (previously passed as the first argument to `Editor.create()`, `Watchdog.create()`, etc.) is deprecated. In v48, pass the DOM element in the configuration object using the editor-type-specific key: `attachTo` for `ClassicEditor`, `root.element` for single-root non-classic editors, and `roots.<name>.element` for `MultiRootEditor`.

For `ClassicEditor`, use `attachTo` only. Passing a DOM element to `root.element` is not supported and triggers a warning, because classic replaces the `attachTo` element with the full editor UI and creates the editable internally. Other editor types use `root.element` or `roots.<name>.element` directly as editable areas.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--migration-examples">

##### Migration examples

The examples below show how to migrate initialization for each editor type.

For `ClassicEditor`:

```
- ClassicEditor.create( document.querySelector( '#editor' ), {
-     initialData: '<p>Hello world!</p>',
-     placeholder: 'Type here...',
-     label: 'Main content'
- } );
+ ClassicEditor.create( {
+     attachTo: document.querySelector( '#editor' ),
+     root: {
+         initialData: '<p>Hello world!</p>',
+         placeholder: 'Type here...',
+         label: 'Main content'
+     }
+ } );

```

For non-classic single-root editors (for example `InlineEditor`, `BalloonEditor`, or `DecoupledEditor`), pass the DOM element through `root.element`:

```
- InlineEditor.create( document.querySelector( '#editor' ), {
-     initialData: '<p>Hello world!</p>',
-     placeholder: 'Type here...'
- } );
+ InlineEditor.create( {
+     root: {
+         element: document.querySelector( '#editor' ),
+         initialData: '<p>Hello world!</p>',
+         placeholder: 'Type here...'
+     },
+ } );

```

In multi-root editors, move source elements and root-specific properties into the `roots` object:

```
- MultiRootEditor.create( {
-     header: document.querySelector( '#header' ),
-     content: document.querySelector( '#content' )
- }, {
-     initialData: {
-         header: '<h2>Header data</h2>',
-         content: '<p>Content data</p>'
-     },
-     placeholder: {
-         header: 'Header',
-         content: 'Type here...'
-     }
- } );
+ MultiRootEditor.create( {
+     roots: {
+         header: {
+             element: document.querySelector( '#header' ),
+             initialData: '<h2>Header data</h2>',
+             placeholder: 'Header'
+         },
+         content: {
+             element: document.querySelector( '#content' ),
+             initialData: '<p>Content data</p>',
+             placeholder: 'Type here...'
+         }
+     }
+ } );

```

Besides editor initialization changes, update related root configuration paths as well:

* `config.rootsAttributes` \-> `config.roots.<rootName>.modelAttributes`
* `config.lazyRoots` \-> `config.roots.<rootName>.lazyLoad`

The `lazyLoad` property is also **deprecated** and will be removed in future versions.

If your integration reads configuration values directly, update access paths as well:

* `config.get( 'initialData' )` \-> `config.get( 'roots.main.initialData' )`
* `config.get( 'placeholder' )` \-> `config.get( 'roots.main.placeholder' )`
* `config.get( 'label' )` \-> `config.get( 'roots.main.label' )`

<a id="ckeditor5/latest/updating/guides/update-to-48.html--dynamic-root-management">

##### Dynamic root management

The legacy signatures of `MultiRootEditor#addRoot()` and `MultiRootEditor#createEditable()` are deprecated and will be removed in a future release. They are replaced with new signatures that align with the way the editor root configuration is specified in `config.roots`.

For `addRoot()`, the `data` and `attributes` options have been renamed to `initialData` and `modelAttributes`, and the new signature also accepts `placeholder` and `label`:

```
 editor.addRoot( 'myRoot', {
-    data: '<p>Initial root data.</p>',
-    attributes: { order: 1 },
+    initialData: '<p>Initial root data.</p>',
+    modelAttributes: { order: 1 },
+    placeholder: 'Type here...',
+    label: 'My root',
     isUndoable: true
 } );

```

For `createEditable()`, pass an options object instead of positional `placeholder` and `label` arguments:

```
- const domElement = editor.createEditable( root, 'Type here...', 'My root' );
+ const domElement = editor.createEditable( root, {
+    placeholder: 'Type here...',
+    label: 'My root'
+ } );

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--table-experimental-features-are-now-default">

#### Table experimental features are now default

In CKEditor 5 v47, we introduced experimental flags for extended table block alignment, improved table border normalization, and table cell type support. Starting with v48, these features are fully stable and enabled by default.

You no longer need to use the `experimentalFlags.useExtendedTableBlockAlignment`, `experimentalFlags.upcastTableBorderZeroAttributes`, and `experimentalFlags.tableCellTypeSupport` configuration options.

Additionally, if you were using the experimental UI plugins (`TablePropertiesUIExperimental` and `TableCellPropertiesUIExperimental`), you should remove them and revert to using the standard `TableProperties` and `TableCellProperties` plugins.

```
 ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        plugins: [
            Table,
-            TablePropertiesEditing,
-            TablePropertiesUIExperimental,
-            TableCellPropertiesEditing,
-            TableCellPropertiesUIExperimental,
+            TableProperties,
+            TableCellProperties,
            // Other plugins.
            // ...
        ],
-        experimentalFlags: {
-            useExtendedTableBlockAlignment: true,
-            upcastTableBorderZeroAttributes: true,
-            tableCellTypeSupport: true
-        }
     } )
     .then( /* ... */ )
     .catch( /* ... */ );

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--export-to-pdf-v2-is-now-the-default">

#### Export to PDF v2 is now the default

Starting with v48, Export to PDF uses version 2 of the HTML to PDF converter API by default. Version 1 is deprecated and available only for backward compatibility.

```
// Before (legacy V1 setup)
exportPdf: {
    version: 1,
    converterUrl: 'https://pdf-converter.cke-cs.com/v1/convert',
    converterOptions: {
        format: 'A4',
        margin_top: '20mm'
    }
}

// Now (v48 default)
exportPdf: {
    // No `version` needed (V2 is default).
    converterUrl: 'https://pdf-converter.cke-cs.com/v2/convert/html-pdf',
    converterOptions: {
        document: {
            size: 'A4',
            margins: { top: '20mm' }
        }
    }
}

```

This snippet highlights only selected changes. The V1 to V2 migration includes additional differences in available options and payload structure.

If your integration still relies on V1 configuration, migrate to V2\. For migration steps and option mapping, see the [migration guide from V1 to V2](https://pdf-converter.cke-cs.com/v2/convert/docs#section/Export-to-PDF-%28v2%29/Migration-guide-from-v1-to-v2) and the [Export to PDF feature guide](#ckeditor5/latest/features/converters/export-pdf.html).

<a id="ckeditor5/latest/updating/guides/update-to-48.html--css-nesting-output-now-follows-native-specificity-more-closely">

#### CSS nesting output now follows native specificity more closely

As part of the preparation for a planned migration to native CSS nesting at the beginning of 2027, we updated the generated CSS output to behave more like native CSS nesting. We are not switching to native CSS nesting yet, but some compiled selectors may now have higher specificity than in earlier releases. We are making this change now to reduce the number of changes needed later.

This mainly affects nested rules written under a list of selectors. In some cases, the final selector may now be more specific than before. Because of this, some custom CSS overrides that worked in earlier versions may no longer apply without changes.

Most integrations should not be affected. However, if you override CKEditor 5 styles with your own CSS, check whether any of your overrides stopped working after the update.

If needed, fix your custom styles by making your override selector more specific or by loading your CSS later so it takes precedence.

The following simplified example shows the kind of difference you may notice:

```
/* Source code */
.ck.ck-button, a.ck.ck-button {
    &.ck-button_with-text {}
}

/* Before */
.ck.ck-button.ck-button_with-text, a.ck.ck-button.ck-button_with-text {}

/* After */
:is(.ck.ck-button, a.ck.ck-button).ck-button_with-text {}

```

The “Before” and “After” selectors look similar, but the second may have higher specificity because `:is()` adopts the specificity of the most specific selector in its list, which can change which rule wins in the cascade.

If you do not override the editor styles, no action is required.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--deprecation-of-the-ckeditorckeditor5-theme-lark-package">

#### Deprecation of the `@ckeditor/ckeditor5-theme-lark` package

The `@ckeditor/ckeditor5-theme-lark` package has been deprecated. The styles from this package have been moved to respective feature packages. All generic styles that affect the editor’s UI more broadly have been moved to the `@ckeditor/ckeditor5-ui` package.

If you import styles from the aggregate stylesheets, such as `ckeditor5/ckeditor5.css` and `ckeditor5-premium-features/ckeditor5-premium-features.css`, you don’t need to change anything.

However, if you followed the [Optimizing build size](#ckeditor5/latest/getting-started/setup/optimizing-build-size.html) guide and imported styles from individual packages, you need to update your imports:

1. Remove the import from the `@ckeditor/ckeditor5-theme-lark` package:  
```  
// Remove this import.  
import '@ckeditor/ckeditor5-theme-lark/dist/index.css';  
```
2. Move the import from the `@ckeditor/ckeditor5-ui` package to the top of your style imports:  
```  
// Move this import to the top of your styles imports.  
import '@ckeditor/ckeditor5-ui/dist/index.css';  
```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--mention-feature-now-persists-uid-as-data-mention-uid-in-the-data-output">

#### Mention feature now persists `uid` as `data-mention-uid` in the data output

The mention feature now outputs a `data-mention-uid` attribute on mention elements in the editor output. This ensures that the same HTML always produces the same editor internal data model.

If you use the default mention converters, no changes are required.

If you defined **custom downcast converters** for mentions (as described in the [customizing the output](#ckeditor5/latest/features/mentions.html--customizing-the-output) guide), update them to include `data-mention-uid` in the output and omit it during clipboard operations:

```
// ❌ Before:
editor.conversion.for( 'downcast' ).attributeToElement( {
    model: 'mention',
    view: ( modelAttributeValue, { writer } ) => {
        if ( !modelAttributeValue ) {
            return;
        }

        return writer.createAttributeElement( 'a', {
            class: 'mention',
            'data-mention': modelAttributeValue.id,
            'href': modelAttributeValue.link
        }, {
            // Make mention attribute to be wrapped by other attribute elements.
            priority: 20,
            // Prevent merging mentions together in clipboard (when `data-mention-uid` is not available).
            id: modelAttributeValue.uid
        } );
    },
    converterPriority: 'high'
} );

// ✅ After:
editor.conversion.for( 'downcast' ).attributeToElement( {
    model: 'mention',
    view: ( modelAttributeValue, { writer, options } ) => {
        if ( !modelAttributeValue ) {
            return;
        }

        return writer.createAttributeElement( 'a', {
            class: 'mention',
            'data-mention': modelAttributeValue.id,
            'href': modelAttributeValue.link,
            // Omit `data-mention-uid` in clipboard (copy/cut) to prevent UIDs duplication.
            ...( !options.isClipboardPipeline && { 'data-mention-uid': modelAttributeValue.uid } )
        }, {
            // Make mention attribute to be wrapped by other attribute elements.
            priority: 20,
            // Prevent merging mentions together in clipboard (when `data-mention-uid` is not available).
            id: modelAttributeValue.uid
        } );
    },
    converterPriority: 'high'
} );

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--collaboration-user-colors-now-use-css-variable-based-styling">

#### Collaboration user colors now use CSS-variable-based styling

The collaboration user coloring implementation has been refactored to use runtime CSS variables instead of using a mixin.

If you use only the default user colors, no changes are required. However, if you specified custom user colors, you can migrate by following these three steps:

1. Remove the `@ckeditor/ckeditor5-collaboration-core/theme/usercolormixin.css` import.
2. Replace `@mixin userColor` definitions with `--ck-user-colors--*` and `--ck-user-colors--*-alpha` CSS variables.  
The old and new approaches look like this:  
```  
/* Before */  
@import "@ckeditor/ckeditor5-collaboration-core/theme/usercolormixin.css";  
@mixin userColor hsla(31, 90%, 43%, 1), hsla(31, 90%, 43%, 0.15), 8;  
@mixin userColor hsla(61, 90%, 43%, 1), hsla(61, 90%, 43%, 0.15), 9;  
```  
```  
/* After */  
:root {
    --ck-user-colors--8: hsla(31, 90%, 43%, 1);
    --ck-user-colors--8-alpha: hsla(31, 90%, 43%, 0.15);

    --ck-user-colors--9: hsla(61, 90%, 43%, 1);
    --ck-user-colors--9-alpha: hsla(61, 90%, 43%, 0.15);  
}  
```
3. Keep the `config.users.colorsCount` option aligned with the total number of defined colors. For the example above (`0-9`), set:  
```  
users: {  
    colorsCount: 10  
}  
```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--alignment-of-ai-features-configuration-options">

#### Alignment of AI features configuration options

The AI part of the configuration has been reworked to provide consistent options across all the features.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--ai-chat-shortcuts">

##### AI Chat Shortcuts

In the [Chat Shortcuts](#ckeditor5/latest/features/ai/ckeditor-ai-chat.html--chat-shortcuts) feature, the `check` property in the shortcut definition (see [config.ai.chat.shortcuts](../../api/module%5Fai%5Faichat%5Faichat-AIChatConfig.html#member-shortcuts) configuration) has been renamed to `commandId`.

If you have any shortcuts defined, update the `check` property as shown below.

Before:

```
{
    id: 'check-correctness',
    label: 'Proofread this document',
    type: 'review',
    check: 'correctness'
}

```

After:

```
{
    id: 'check-correctness',
    label: 'Proofread this document',
    type: 'review',
    commandId: 'correctness'
}

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--ai-quick-actions">

##### AI Quick Actions

In the [Quick Actions](#ckeditor5/latest/features/ai/ckeditor-ai-actions.html) feature, the `type` value for [config.ai.quickActions.extraCommands](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActionsConfig.html#member-extraCommands) has been changed from uppercase to lowercase. Instead of using `'CHAT'` or `'ACTION'`, use `'chat'` and `'action'` now.

Additionally, the `label` property has been introduced in place of the `displayedPrompt` property in the [config.ai.quickActions.extraCommands](../../api/module%5Fai%5Faiquickactions%5Faiquickactions-AIQuickActionsConfig.html#member-extraCommands) configuration. The `displayedPrompt` is now required only for commands with type `'chat'`.

If you are using `extraCommands` with any command of type `'action'`, it should now have the `label` property instead of `displayedPrompt`.

Before:

```
{
    id: 'add-quote-from-famous-person',
    displayedPrompt: 'Add a quote from a famous person',
    prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
    type: 'action'
}

```

After:

```
{
    id: 'add-quote-from-famous-person',
    label: 'Add a quote from a famous person',
    prompt: 'Add a quote from a known person, which would make sense in the context of the selected text.',
    type: 'action'
}

```

If you are using any `extraCommands` with type `'chat'`, it requires both `label` and `displayedPrompt` properties.

Before:

```
{
    id: 'summarize-in-bullet-points',
    displayedPrompt: 'Summarize in 5 bullet points',
    prompt: 'Summarize the selected text in 5 bullet points.',
    type: 'chat'
}

```

After:

```
{
    id: 'summarize-in-bullet-points',
    label: 'Summarize',
    displayedPrompt: 'Summarize in 5 bullet points',
    prompt: 'Summarize the selected text in 5 bullet points.',
    type: 'chat'
}

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--ai-ui-styling-variables-no-longer-affecting-the-ui">

##### AI UI styling variables no longer affecting the UI

AI UI styling has been aligned with the editor-wide styling system, and selected AI-specific CSS variables no longer affect the UI.

The AI UI now uses the font family defined by `--ck-font-face`. Because of this, the following variables **no longer change AI UI font styling**:

* `--ck-ai-balloon-font-family`
* `--ck-ai-chat-font-family`
* `--ck-ai-web-source-tooltip-font-family`
* `--ck-ai-review-font-family`

Additionally, AI buttons now use generic classes (`ck-ai-button-primary`, `ck-ai-button-secondary`, and `ck-ai-button-tertiary`), so the variables below **no longer affect the UI**:

* `--ck-ai-border-color-button`
* `--ck-ai-chat-feed-item-color-actions-button-hover`
* `--ck-ai-chat-feed-item-color-show-changes-toggle-active-background`
* `--ck-ai-chat-feed-item-color-show-changes-toggle-hover-background`
* `--ck-ai-chat-feed-item-color-show-changes-toggle-hover-color`
* `--ck-ai-chat-feed-item-color-show-changes-toggle-on-background`
* `--ck-ai-chat-feed-item-color-show-changes-toggle-on-color`
* `--ck-ai-chat-feed-item-color-text`
* `--ck-ai-chat-feed-loader-icon-color`
* `--ck-ai-chat-suggestion-border-hover-color`
* `--ck-ai-header-border-color-button`
* `--ck-ai-header-color-text`
* `--ck-ai-loader-icon-color`
* `--ck-ai-loader-icon-dot-color`
* `--ck-ai-review-check-list-model-dropdown-active-color`
* `--ck-ai-review-check-list-model-dropdown-hover-background-color`

<a id="ckeditor5/latest/updating/guides/update-to-48.html--use-of-string-values-instead-of-enums">

##### Use of `string` values instead of `enums`

The use of TypeScript `enums` as part of the public CKEditor 5 AI API has been removed. To simplify usage, _union of strings_ is now used instead.

If you have used any of the `AIContextItemType`, `AIContextTextResourceType`, or `AIChatShortcutType` enums, replace them with the corresponding string values. Please refer to the documentation of [AIContextItemType](../../api/module%5Fai%5Faicore%5Fmodel%5Faicontext-AIContextItemType.html), [AIContextTextResourceType](../../api/module%5Fai%5Faicore%5Fmodel%5Faicontext-AIContextTextResourceType.html), and [AIChatShortcutType](../../api/module%5Fai%5Faichatshortcuts%5Faichatshortcuts-AIChatShortcutType.html).  
Additionally, `AIChatShortcutTypeValue` has been removed as `AIChatShortcutType` now serves the same purpose.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--ai-feature-ui-button-css-classes-and-color-variables">

#### AI feature UI: button CSS classes and color variables

AI toolbars, panels, and related UI were refactored: controls now share button classes, and colors are driven from a single palette plus feature-level `--ck-color-ai-*` tokens. If you override AI styles in your integration, use the information below to update custom CSS.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--default-ai-color-palette">

##### Default AI color palette

The package ships a root palette. Feature styles reference these values directly or through semantic `--ck-color-ai-*` aliases. Override the palette for broad theming; use feature tokens when you need a narrower change.

Palette entries use **relative color** syntax (`hsla(from var(--ck-color-ai-…) …)`), so changing a main color like `--ck-color-ai-accent-700` automatically adjusts the relative colors.

```
:root {
    /* Alpha values */
    --ck-color-ai-alpha-1: 0.1;
    --ck-color-ai-alpha-2: 0.2;
    --ck-color-ai-alpha-3: 0.3;
    --ck-color-ai-alpha-4: 0.4;
    --ck-color-ai-alpha-5: 0.5;
    --ck-color-ai-alpha-6: 0.6;
    --ck-color-ai-alpha-7: 0.7;
    --ck-color-ai-alpha-8: 0.8;
    --ck-color-ai-alpha-9: 0.9;

    /* Neutrals */
    --ck-color-ai-black: hsl(0, 0%, 0%);
    --ck-color-ai-gray-900: hsl(0, 0%, 20%);
    --ck-color-ai-gray-900-a5: hsla(from var(--ck-color-ai-gray-900) h s l / var(--ck-color-ai-alpha-5));
    --ck-color-ai-gray-600: hsl(0, 0%, 44%);
    --ck-color-ai-gray-600-a5: hsla(from var(--ck-color-ai-gray-600) h s l / var(--ck-color-ai-alpha-5));
    --ck-color-ai-gray-300: hsl(216, 5%, 81%);
    --ck-color-ai-gray-100: hsl(0, 0%, 94%);
    --ck-color-ai-gray-50: hsl(0, 0%, 96%);
    --ck-color-ai-gray-25: hsl(0, 0%, 98%);
    --ck-color-ai-white: hsl(0, 0%, 100%);
    --ck-color-ai-white-50: hsla(from var(--ck-color-ai-white) h s l / var(--ck-color-ai-alpha-5));

    /* Accent (purple / violet); higher step = darker */
    --ck-color-ai-accent-700: hsl(263, 59%, 52%);
    --ck-color-ai-accent-700-a1: hsla(from var(--ck-color-ai-accent-700) h s l / var(--ck-color-ai-alpha-1));
    --ck-color-ai-accent-700-a2: hsla(from var(--ck-color-ai-accent-700) h s l / var(--ck-color-ai-alpha-2));
    --ck-color-ai-accent-700-a3: hsla(from var(--ck-color-ai-accent-700) h s l / var(--ck-color-ai-alpha-3));
    --ck-color-ai-accent-700-a5: hsla(from var(--ck-color-ai-accent-700) h s l / var(--ck-color-ai-alpha-5));
    --ck-color-ai-accent-800: hsl(263, 59%, 40%);
    --ck-color-ai-accent-800-a8: hsla(from var(--ck-color-ai-accent-800) h s l / var(--ck-color-ai-alpha-8));
    --ck-color-ai-accent-400: hsl(262, 64%, 78%);
    --ck-color-ai-accent-400-a5: hsla(from var(--ck-color-ai-accent-400) h s l / var(--ck-color-ai-alpha-5));
    --ck-color-ai-accent-100: hsl(261, 100%, 93%);
    --ck-color-ai-accent-50: hsl(262, 100%, 96%);

    /* Shadows */
    --ck-color-ai-shadow: hsla(from var(--ck-color-ai-black) h s l / var(--ck-color-ai-alpha-1));

    /* Insertion (green) / suggestion markers */
    --ck-color-ai-insertion-border: hsla(128, 71%, 40%, 0.35);
    --ck-color-ai-insertion-background: hsla(128, 71%, 65%, 0.35);
    --ck-color-ai-insertion-border-active: hsla(128, 71%, 25%, 0.5);
    --ck-color-ai-insertion-background-active: hsla(128, 71%, 50%, 0.5);

    /* Deletion (red) / suggestion markers */
    --ck-color-ai-deletion-border: hsla(345, 71%, 40%, 0.35);
    --ck-color-ai-deletion-background: hsla(345, 71%, 65%, 0.35);
    --ck-color-ai-deletion-stroke: hsla(345, 71%, 20%, 0.5);
    --ck-color-ai-deletion-border-active: hsla(345, 71%, 25%, 0.5);
    --ck-color-ai-deletion-bg-active: hsla(345, 71%, 50%, 0.5);

    /* Inactive suggestion */
    --ck-color-ai-inactive-insertion-border: hsla(128, 1%, 73%, 0.35);
    --ck-color-ai-inactive-insertion-background: hsla(128, 6%, 93%, 0.35);
    --ck-color-ai-inactive-deletion-border: hsla(345, 1%, 74%, 0.35);
    --ck-color-ai-inactive-deletion-background: hsla(345, 11%, 95%, 0.35);
    --ck-color-ai-inactive-deletion-stroke: hsla(0, 1%, 62%, 0.35);

    /* Notification */
    --ck-color-ai-error-background: hsl(15, 100%, 97%);
    --ck-color-ai-error-border: hsl(14, 100%, 68%);
    --ck-color-ai-warning-background: hsl(37, 100%, 96.5%);
    --ck-color-ai-warning-border: hsl(36, 100%, 68%);

    /* Prompt animation */
    --ck-color-ai-prompt-glow: hsl(55, 100%, 95%);
}

```

<a id="ckeditor5/latest/updating/guides/update-to-48.html--shared-ai-button-classes">

##### Shared AI button classes

Primary, secondary, and tertiary actions use the same classes everywhere:

* `ck-ai-button-primary`
* `ck-ai-button-secondary`
* `ck-ai-button-tertiary`

Several older variables only fed one-off button styling; those hooks are **superseded** by the classes and theme rules. See the details below.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--css-custom-property-migration">

##### CSS custom property migration

The **Change type** column uses:

* **Superseded** – no replacement variable; the shared button classes are used instead.
* **Renamed** – override the new `--ck-color-ai-*` (or underlying palette) token.
* **Restructured** – the property now composes palette variables; prefer the listed replacements (composite variables such as `--ck-ai-skeleton-item-background` or `--ck-ai-spinner-background` still exist if you override the entire value).

| Old                                                                 | Change type  | New                                                                                   |
| ------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
| \--ck-ai-border-color-button                                        | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-actions-button-hover                  | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-show-changes-toggle-active-background | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-show-changes-toggle-hover-background  | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-show-changes-toggle-hover-color       | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-show-changes-toggle-on-background     | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-show-changes-toggle-on-color          | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-item-color-text                                  | Superseded   | —                                                                                     |
| \--ck-ai-chat-feed-loader-icon-color                                | Superseded   | —                                                                                     |
| \--ck-ai-chat-suggestion-border-hover-color                         | Superseded   | —                                                                                     |
| \--ck-ai-header-border-color-button                                 | Superseded   | —                                                                                     |
| \--ck-ai-header-color-text                                          | Superseded   | —                                                                                     |
| \--ck-ai-loader-icon-color                                          | Superseded   | —                                                                                     |
| \--ck-ai-loader-icon-dot-color                                      | Superseded   | —                                                                                     |
| \--ck-ai-review-check-list-model-dropdown-active-color              | Superseded   | —                                                                                     |
| \--ck-ai-review-check-list-model-dropdown-hover-background-color    | Superseded   | —                                                                                     |
| \--ck-ai-actions-balloon-disclaimer-text-color                      | Renamed      | \--ck-color-ai-actions-balloon-disclaimer-text                                        |
| \--ck-ai-background-color-action-button                             | Renamed      | \--ck-color-ai-chat-primary-button-background                                         |
| \--ck-ai-border-color-main                                          | Renamed      | \--ck-color-ai-chat-border-main                                                       |
| \--ck-ai-button-primary-active-background-color                     | Renamed      | \--ck-color-ai-button-primary-background-active                                       |
| \--ck-ai-button-primary-background-color                            | Renamed      | \--ck-color-ai-button-primary-background                                              |
| \--ck-ai-button-primary-color                                       | Renamed      | \--ck-color-ai-button-primary-text                                                    |
| \--ck-ai-button-primary-disabled-background-color                   | Renamed      | \--ck-color-ai-button-primary-background-disabled                                     |
| \--ck-ai-button-primary-disabled-color                              | Renamed      | \--ck-color-ai-button-primary-text-disabled                                           |
| \--ck-ai-button-primary-hover-background-color                      | Renamed      | \--ck-color-ai-button-primary-background-hover                                        |
| \--ck-ai-button-secondary-active-background-color                   | Renamed      | \--ck-color-ai-button-secondary-background-active                                     |
| \--ck-ai-button-secondary-background-color                          | Renamed      | \--ck-color-ai-button-secondary-background                                            |
| \--ck-ai-button-secondary-border-color                              | Renamed      | \--ck-color-ai-button-secondary-border                                                |
| \--ck-ai-button-secondary-color                                     | Renamed      | \--ck-color-ai-button-secondary-text                                                  |
| \--ck-ai-button-secondary-disabled-background-color                 | Renamed      | \--ck-color-ai-button-secondary-background-disabled                                   |
| \--ck-ai-button-secondary-disabled-border-color                     | Renamed      | \--ck-color-ai-button-secondary-border-disabled                                       |
| \--ck-ai-button-secondary-disabled-color                            | Renamed      | \--ck-color-ai-button-secondary-text-disabled                                         |
| \--ck-ai-button-secondary-hover-background-color                    | Renamed      | \--ck-color-ai-button-secondary-background-hover                                      |
| \--ck-ai-button-tertiary-active-background-color                    | Renamed      | \--ck-color-ai-button-tertiary-background-active                                      |
| \--ck-ai-button-tertiary-active-color                               | Renamed      | \--ck-color-ai-button-tertiary-text-active                                            |
| \--ck-ai-button-tertiary-background-color                           | Renamed      | \--ck-color-ai-button-tertiary-background                                             |
| \--ck-ai-button-tertiary-color                                      | Renamed      | \--ck-color-ai-button-tertiary-text                                                   |
| \--ck-ai-button-tertiary-disabled-background-color                  | Renamed      | \--ck-color-ai-button-tertiary-background-disabled                                    |
| \--ck-ai-button-tertiary-disabled-color                             | Renamed      | \--ck-color-ai-button-tertiary-text-disabled                                          |
| \--ck-ai-button-tertiary-hover-active-background-color              | Renamed      | \--ck-color-ai-button-tertiary-background-hover-active                                |
| \--ck-ai-button-tertiary-hover-active-color                         | Renamed      | \--ck-color-ai-button-tertiary-text-hover-active                                      |
| \--ck-ai-button-tertiary-hover-background-color                     | Renamed      | \--ck-color-ai-button-tertiary-background-hover                                       |
| \--ck-ai-button-tertiary-hover-color                                | Renamed      | \--ck-color-ai-button-tertiary-text-hover                                             |
| \--ck-ai-chat-button-active-background-color                        | Renamed      | \--ck-color-ai-chat-button-active-background                                          |
| \--ck-ai-chat-button-active-color                                   | Renamed      | \--ck-color-ai-chat-button-active                                                     |
| \--ck-ai-chat-button-hover-color                                    | Renamed      | \--ck-color-ai-chat-button-hover                                                      |
| \--ck-ai-chat-color-icon                                            | Renamed      | \--ck-color-ai-chat-icon                                                              |
| \--ck-ai-chat-color-text                                            | Renamed      | \--ck-color-ai-chat-text                                                              |
| \--ck-ai-chat-controls-loader-color                                 | Renamed      | \--ck-color-ai-chat-controls-loader                                                   |
| \--ck-ai-chat-controls-loader-icon-color                            | Renamed      | \--ck-color-ai-chat-controls-loader-icon                                              |
| \--ck-ai-chat-controls-loader-icon-dot-active-color                 | Renamed      | \--ck-color-ai-chat-controls-loader-icon-dot-active                                   |
| \--ck-ai-chat-controls-loader-icon-dot-color                        | Renamed      | \--ck-color-ai-chat-controls-loader-icon-dot                                          |
| \--ck-ai-chat-feed-interaction-header-capabilities-color-text       | Renamed      | \--ck-color-ai-chat-feed-interaction-header-capabilities-text                         |
| \--ck-ai-chat-feed-item-color-background                            | Renamed      | \--ck-color-ai-chat-feed-item-background                                              |
| \--ck-ai-chat-feed-item-color-background-secondary                  | Renamed      | \--ck-color-ai-chat-feed-item-background-secondary                                    |
| \--ck-ai-chat-flash-color                                           | Renamed      | \--ck-color-ai-chat-flash                                                             |
| \--ck-ai-chat-flash-color-text                                      | Renamed      | \--ck-color-ai-chat-flash-text                                                        |
| \--ck-ai-chat-suggestion-icon-default-color                         | Renamed      | \--ck-color-ai-chat-suggestion-icon-default                                           |
| \--ck-ai-chat-user-context-background                               | Renamed      | \--ck-color-ai-chat-user-context-background                                           |
| \--ck-ai-disclaimer-background-color                                | Renamed      | \--ck-color-ai-disclaimer-background                                                  |
| \--ck-ai-disclaimer-border-color                                    | Renamed      | \--ck-color-ai-disclaimer-border                                                      |
| \--ck-ai-disclaimer-text-color                                      | Renamed      | \--ck-color-ai-disclaimer-text                                                        |
| \--ck-ai-font-color-action-button                                   | Renamed      | \--ck-color-ai-chat-primary-button-text                                               |
| \--ck-ai-header-color-icon                                          | Renamed      | \--ck-color-ai-header-icon                                                            |
| \--ck-ai-notification-color-text                                    | Renamed      | \--ck-color-ai-notification-text                                                      |
| \--ck-ai-notification-error-color-background                        | Renamed      | \--ck-color-ai-notification-error-background                                          |
| \--ck-ai-notification-error-color-border                            | Renamed      | \--ck-color-ai-notification-error-border                                              |
| \--ck-ai-notification-warning-color-background                      | Renamed      | \--ck-color-ai-notification-warning-background                                        |
| \--ck-ai-notification-warning-color-border                          | Renamed      | \--ck-color-ai-notification-warning-border                                            |
| \--ck-ai-quick-actions-button-background-color                      | Renamed      | \--ck-color-ai-quick-actions-button-background                                        |
| \--ck-ai-quick-actions-button-color                                 | Renamed      | \--ck-color-ai-quick-actions-button                                                   |
| \--ck-ai-quick-actions-list-item-group-row-color                    | Renamed      | \--ck-color-ai-quick-actions-list-item-group-row                                      |
| \--ck-ai-review-border-color-button                                 | Renamed      | \--ck-color-ai-review-border-button                                                   |
| \--ck-ai-review-check-list-item-active-border-color                 | Renamed      | \--ck-color-ai-review-check-list-item-active-border                                   |
| \--ck-ai-review-check-list-item-description-color                   | Renamed      | \--ck-color-ai-review-check-list-item-description                                     |
| \--ck-ai-review-check-list-item-hover-border-color                  | Renamed      | \--ck-color-ai-review-check-list-item-hover-border                                    |
| \--ck-ai-review-check-list-item-title-color                         | Renamed      | \--ck-color-ai-review-check-list-item-title                                           |
| \--ck-ai-review-check-list-item-title-icon-color                    | Renamed      | \--ck-color-ai-review-check-list-item-title-icon                                      |
| \--ck-ai-review-color-icon                                          | Renamed      | \--ck-color-ai-review-icon                                                            |
| \--ck-ai-review-color-text                                          | Renamed      | \--ck-color-ai-review-text                                                            |
| \--ck-ai-suggestion-inactive-color-background                       | Renamed      | \--ck-color-ai-suggestion-inactive-background                                         |
| \--ck-ai-suggestion-inactive-color-border                           | Renamed      | \--ck-color-ai-suggestion-inactive-border                                             |
| \--ck-ai-suggestion-marker-deletion-background-color                | Renamed      | \--ck-color-ai-suggestion-marker-deletion-background                                  |
| \--ck-ai-suggestion-marker-deletion-background-color-active         | Renamed      | \--ck-color-ai-suggestion-marker-deletion-background-active                           |
| \--ck-ai-suggestion-marker-deletion-border-color                    | Renamed      | \--ck-color-ai-suggestion-marker-deletion-border                                      |
| \--ck-ai-suggestion-marker-deletion-border-color-active             | Renamed      | \--ck-color-ai-suggestion-marker-deletion-border-active                               |
| \--ck-ai-suggestion-marker-deletion-stroke-color                    | Renamed      | \--ck-color-ai-suggestion-marker-deletion-stroke                                      |
| \--ck-ai-suggestion-marker-insertion-background-color               | Renamed      | \--ck-color-ai-suggestion-marker-insertion-background                                 |
| \--ck-ai-suggestion-marker-insertion-background-color-active        | Renamed      | \--ck-color-ai-suggestion-marker-insertion-background-active                          |
| \--ck-ai-suggestion-marker-insertion-border-color                   | Renamed      | \--ck-color-ai-suggestion-marker-insertion-border                                     |
| \--ck-ai-suggestion-marker-insertion-border-color-active            | Renamed      | \--ck-color-ai-suggestion-marker-insertion-border-active                              |
| \--ck-ai-web-source-tooltip-title-color                             | Renamed      | \--ck-color-ai-chat-web-source-tooltip-title                                          |
| \--ck-ai-web-source-tooltip-url-color                               | Renamed      | \--ck-color-ai-chat-web-source-tooltip-url                                            |
| \--ck-ai-chat-shortcuts-prompt-input-animation-border               | Restructured | \--ck-color-ai-chat-shortcuts-prompt-animation-border                                 |
| \--ck-ai-chat-shortcuts-prompt-input-animation-box-shadow           | Restructured | \--ck-color-ai-chat-shortcuts-prompt-animation-glow-ring                              |
| \--ck-ai-skeleton-item-background                                   | Restructured | \--ck-color-ai-core-skeleton-gradient-edge, \--ck-color-ai-core-skeleton-gradient-mid |
| \--ck-ai-spinner-background                                         | Restructured | \--ck-color-ai-core-spinner-gradient-start, \--ck-color-ai-core-spinner-gradient-end  |
| \--ck-ai-spinner-mask                                               | Restructured | \--ck-color-ai-core-spinner-mask-edge                                                 |

For **Restructured** rows, prefer tuning the listed `--ck-color-ai-*` variables (or the root palette above) so derived UI stays coherent.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--removal-of-enum-as-uploadcare-source-type">

#### Removal of `enum` as Uploadcare source type

The use of TypeScript `enums` as part of the public CKEditor 5 Uploadcare API has been removed. To simplify usage, _union of strings_ is now used instead.

If you have used the `UploadcareSource` enum, replace it with the corresponding string value. You can see available values in the [UploadcareSource](../../api/module%5Fuploadcare%5Fuploadcareconfig-UploadcareSource.html) documentation. If you have used the `UploadcareSourceValue` type, use `UploadcareSource` instead.

<a id="ckeditor5/latest/updating/guides/update-to-48.html--package-generator-modernization-and-simpler-project-output">

#### Package generator modernization and simpler project output

We used the sunsetting of old installation methods as an opportunity to significantly modernize `ckeditor5-package-generator` in its new major `v6` release and simplify the projects it creates.

The generated package setup moved from webpack to Vite 8 and Vitest (powered by Rolldown), which improves developer experience and performance.

The updated generator output is also easier to work with day to day, both when developing your package and when preparing it for publishing. We recommend migrating existing custom package projects to the new generator output to align with the current CKEditor 5 tooling direction.

For migration details and updated usage instructions, see the [Package generator guide](#ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html).

<a id="ckeditor5/latest/updating/guides/updating-ckeditor-5.html">source file: "ckeditor5/latest/updating/guides/updating-ckeditor-5.html"</a>

## Updating CKEditor 5

<a id="ckeditor5/latest/updating/guides/updating-ckeditor-5.html--updating-the-editor">

### Updating the editor

CKEditor 5 is delivered in several ways and the most flexible and popular one is by using npm packages. The updating process is simple and narrows down to, depending on the installation method, downloading a new package or updating package versions in the `package.json` file.

Before proceeding with an update, it is highly recommended to [read the release notes](https://github.com/ckeditor/ckeditor5/releases) for the latest version to learn about all changes introduced in the release. You should especially pay attention to any possible [breaking changes](#ckeditor5/latest/updating/versioning-policy.html--breaking-changes). This step is crucial if you develop your own custom features and modify the editor, as sometimes, changes in our code might affect these custom solutions.

To help you with a smooth update, we have prepared migration guides that describe adjustments that need to be done before moving to the production environment. You can find them in the sidebar located on the left side of the page.

You can simply visit our [CKEditor 5 download page](https://ckeditor.com/ckeditor-5/download/) or [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) and get the latest editor version from there. However, if you created your own customized editor, the process can be described in a few steps:

1. Read the changelog.
2. Update your packages.
3. Read the migration guide.
4. Reinstall packages and rebuild the editor.
5. Test your editor.

Below you will find an example that will guide you through the updating process and give you an idea on how it should be done.

<a id="ckeditor5/latest/updating/guides/updating-ckeditor-5.html--example">

#### Example

Imagine that you use the editor in and older version and you want to update it to the current 48.0.0 version.

The first step is to identify changes introduced since the old version, so you navigate update guides (found on the left) to identify any possible breaking changes between the old version and the current. These guides will navigate you through any necessary code changes.

When you already know what has changed and which parts of your custom code need to be adjusted, it is time to make the update.

This can be done by updating the `package.json` file with the latest editor version (currently 48.0.0) or using some automated tool (like [npm-check-updates](https://www.npmjs.com/package/npm-check-updates)):

```
    "dependencies": {
        "@ckeditor/ckeditor5-adapter-ckfinder": "^48.0.0",
        "@ckeditor/ckeditor5-autoformat": "^48.0.0",
        "@ckeditor/ckeditor5-basic-styles": "^48.0.0",
        "@ckeditor/ckeditor5-block-quote": "^48.0.0",
        "@ckeditor/ckeditor5-ckfinder": "^48.0.0",
        "@ckeditor/ckeditor5-cloud-services": "^48.0.0",
        "@ckeditor/ckeditor5-editor-classic": "^48.0.0",
        "@ckeditor/ckeditor5-essentials": "^48.0.0",
        "@ckeditor/ckeditor5-heading": "^48.0.0",
        "@ckeditor/ckeditor5-image": "^48.0.0",
        "@ckeditor/ckeditor5-indent": "^48.0.0",
        "@ckeditor/ckeditor5-link": "^48.0.0",
        "@ckeditor/ckeditor5-list": "^48.0.0",
        "@ckeditor/ckeditor5-media-embed": "^48.0.0",
        "@ckeditor/ckeditor5-paragraph": "^48.0.0",
        "@ckeditor/ckeditor5-paste-from-office": "^48.0.0",
        "@ckeditor/ckeditor5-table": "^48.0.0",
        "@ckeditor/ckeditor5-typing": "^48.0.0"
    }

```

Finally, you reinstall the packages and rebuild the editor. Note that sometimes it might be required to remove the `package-lock.json` or `yarn.lock` files.

```
rm -rf node_modules && npm install && npm run build

```

This is it! Your editor is updated and now you can focus on adjusting your custom solutions (if needed). If you use real-time collaboration, you should check the next section.

<a id="ckeditor5/latest/updating/guides/updating-ckeditor-5.html--real-time-collaboration">

#### Real-time collaboration

While using real-time collaboration it is important to remember about preparing existing documents for the updated editor. Basically, it is not possible to join the document that was created with a CKEditor 5 version different than the one used by the client. For example, imagine a situation when the document has been initialized with the editor version 30.0.0 and after the update, a user connects to this document with the editor version 31.0.0\. In such a case, an error about an incompatible engine version will be thrown.

A collaboration session will be removed 24 hours after the last user disconnects. You can also manually [flush](https://help.cke-cs.com/api/v4/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete) any existing collaboration sessions using the [Cloud Services REST API](#cs/latest/developer-resources/apis/overview.html). After the collaboration session removal, users will be able to connect to the documents using a new editor.

<a id="ckeditor5/latest/updating/guides/updating-from-older-versions.html">source file: "ckeditor5/latest/updating/guides/updating-from-older-versions.html"</a>

## Updating from older CKEditor 5 versions

If you are upgrading a project from an older version of CKEditor 5, it is best to update one version at a time to avoid unexpected issues.

After upgrading your project to version 42, return to the current documentation and continue updating to the latest version.

<a id="ckeditor5/latest/updating/index.html">source file: "ckeditor5/latest/updating/index.html"</a>

## CKEditor 5 updates and maintenance

CKEditor 5 is an active, rapidly developing software project. It is, therefore, important to keep it updated and in best condition for stability and safety reasons.

<a id="ckeditor5/latest/updating/index.html--migration-to-cdn">

### Migration to CDN

Migrate your CKEditor 5 from an NPM-based installation to a CDN-based one (for example [Vanilla JS](#ckeditor5/latest/updating/migrations/vanilla-js.html)). CDN-based installations can simplify the setup process by providing a bundler-agnostic way to lazy initialization of CKEditor 5 scripts and styles injection. It reduces complexity in the project setup.

<a id="ckeditor5/latest/updating/index.html--new-installation-methods">

### New installation methods

This section will explore the [new installation methods](#ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html) introduced in CKEditor 5 v42.0.0\. These methods make CKEditor 5 much easier to use by reducing the number of possible installation paths and removing most of the limitations of the old methods.

<a id="ckeditor5/latest/updating/index.html--migration-from-ckeditor-4">

### Migration from CKEditor 4

If you want to switch to CKEditor 5 from our previous product, CKEditor 4, please refer to the dedicated [Migration from CKEditor 4](#ckeditor5/latest/updating/ckeditor4/migration-from-ckeditor-4.html) guide that will explain all the differences between these two products and help you make the switch.

<a id="ckeditor5/latest/updating/index.html--daily-maintenance-of-regular-operation-of-ckeditor-5">

### Daily maintenance of regular operation of CKEditor 5

For general tips on how to take care of your CKEditor 5 installation, please refer to the [Maintaining your editor](#ckeditor5/latest/updating/maintaining.html) guide for tips on how to provide the daily service and make the editor work efficiently and without interruptions.

<a id="ckeditor5/latest/updating/index.html--ckeditor-5-versioning-policy-and-release-process">

### CKEditor 5 versioning policy and release process

Regular code releases bring new features and improvements to CKEditor5\. Visit the [Versioning policy](#ckeditor5/latest/updating/versioning-policy.html) section to check release practices and versioning strategy.

<a id="ckeditor5/latest/updating/index.html--updating-your-ckeditor-5">

### Updating your CKEditor 5

Visit the [Updating CKEditor 5](#ckeditor5/latest/updating/guides/updating-ckeditor-5.html) guide for information on how to update your installation to the newest available stable version of the software. Visit the dedicated update guides for specific CKEditor 5 release versions if you need to catch up with the latest release.

<a id="ckeditor5/latest/updating/maintaining.html">source file: "ckeditor5/latest/updating/maintaining.html"</a>

## Maintaining your editor

CKEditor 5 is an active, rapidly developing software project. It is, therefore, important to keep in touch with all the new features and APIs, changes and bug fixes that are periodically released. As in the case of every software project, it is always wise and highly advised to keep your copy of CKEditor 5 and all plugins up-to-date to maintain the highest level of security and stability. Updating is an important process that should become your routine. Our team constantly introduces new features, bug fixes and improvements, so keeping the editor up-to-date is a way to make sure that you get the best out of CKEditor 5.

<a id="ckeditor5/latest/updating/maintaining.html--daily-maintenance">

### Daily maintenance

<a id="ckeditor5/latest/updating/maintaining.html--upgrade-regularly">

#### Upgrade regularly

CKEditor 5 should be [updated frequently](#ckeditor5/latest/updating/guides/updating-ckeditor-5.html), as bug fixes and new features are not backported. While installing and using a CKEditor 5 instance, especially when adding new features, always make sure all the packages are of the same (preferably latest) version. If this requirement is not met, errors may occur.

<a id="ckeditor5/latest/updating/maintaining.html--use-builder-to-add-plugins">

#### Use Builder to add plugins

Some releases would bring new features and new plugins and sometimes replace old ones and make them obsolete. If you want to install additional plugins, it is easier and safer to use the [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) instead of adding them manually. This will reduce the risk of omitting plugin dependencies.

<a id="ckeditor5/latest/updating/maintaining.html--safety">

### Safety

Observe any security alerts that are published by the CKEditor 5 team, especially the [Security Advisories](https://github.com/ckeditor/ckeditor5/security/advisories). Always act promptly to apply patches and upgrades as soon as these are released. Keeping your editor up-to-date is crucial to the security and integrity of you content and data. If you are using framework integrations, always follow any information provided by framework developers, too.

<a id="ckeditor5/latest/updating/maintaining.html--data-backup">

#### Data backup

Whatever your approach toward updates might be, always remember to keep a fresh backup of your data. Whether a local solution is used, an on-premises server or the autosave feature, create regular backups of your database and files.

<a id="ckeditor5/latest/updating/migrations/angular.html">source file: "ckeditor5/latest/updating/migrations/angular.html"</a>

## Migrating Angular CKEditor 5 integration from npm to CDN

This guide will help you migrate Angular CKEditor 5 integration from an NPM-based installation to a CDN-based one.

<a id="ckeditor5/latest/updating/migrations/angular.html--prerequisites">

### Prerequisites

Remove the existing CKEditor 5 packages from your project. If you are using the NPM-based installation, you can remove it by running the following command:

```
npm uninstall ckeditor5 ckeditor5-premium-features

```

Upgrade the CKEditor 5 Angular integration to the latest version. You can find it in the [Angular integration](#ckeditor5/latest/getting-started/installation/cloud/angular.html) documentation.

Ensure that your testing suite uses real web browser environments for testing. If you are using `jsdom` or any other environment without a real DOM, you may need to adjust the testing suite configuration to use a real browser because CDN script injection might not be recognized properly in such environments.

<a id="ckeditor5/latest/updating/migrations/angular.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/migrations/angular.html--step-1-remove-ckeditor-5-imports">

#### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your Angular components, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/angular.html--step-2-update-your-angular-components-to-use-cdn">

#### Step 2: Update your Angular components to use CDN

Replace the CKEditor 5 NPM package imports with the CDN script imports and use the `loadCKEditorCloud` function to load the CKEditor 5 scripts. The `loadCKEditorCloud` function is a part of the `@ckeditor/ckeditor5-angular` package and is used to load CKEditor 5 scripts from the CKEditor Cloud service.

**Before:**

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor, Bold, Essentials, Italic, Mention, Paragraph, Undo } from 'ckeditor5';
import { SlashCommand } from 'ckeditor5-premium-features';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    encapsulation: ViewEncapsulation.None,
    imports: [ CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';

    public Editor = ClassicEditor;
    public config = {
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        plugins: [ Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo ],
        toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        // ... Other configuration ....
    }
}

```

**After:**

```
// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';

@Component( {
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
    encapsulation: ViewEncapsulation.None,
    imports: [ CKEditorModule ],
    standalone: true
} )
export class AppComponent {
    title = 'angular';

    public Editor;
    public config;

    public ngOnInit() {
        // ADDED
        loadCKEditorCloud( {
            version: '43.0.0'
        } )
        .then( this._setupEditor.bind( this ) );
    }

    private _setupEditor( cloud ) {
        const {
            ClassicEditor, Bold, Essentials, Italic,
            Mention, Paragraph, SlashCommand, Undo
        } = cloud.CKEditor;

        this.Editor = ClassicEditor;
        this.config = {
            licenseKey: '<YOUR_LICENSE_KEY>',
            plugins: [ Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
            // ... Other configuration ....
        }
    }
}

```

```
// app.component.html

<ckeditor
    *ngIf="Editor"
    [editor]="Editor"
    [config]="config"
    <!-- ... -->
>
</ckeditor>

```

<a id="ckeditor5/latest/updating/migrations/angular.html--step-3-optional-migrate-the-ckeditor-5-angular-integration-testing-suite">

#### Step 3 (Optional): Migrate the CKEditor 5 Angular integration testing suite

If you have any tests that use CKEditor 5 objects, you need to update them to use the `loadCKEditorCloud` function. Here is an example of migrating a test that uses the `ClassicEditor` object:

**Before:**

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';

it( 'ClassicEditor test', () => {
    // Your test that uses the CKEditor 5 object.
} );

```

**After:**

```
import { loadCKEditorCloud } from '@ckeditor/ckeditor5-angular';

let cloud;

beforeEach( async () => {
    cloud = await loadCKEditorCloud( {
        version: '48.0.0',
    } );
} );

it( 'ClassicEditor test', () => {
    const { ClassicEditor, /* ... other imports */ } = cloud.CKEditor;

    // Your test that uses the CKEditor 5 object.
} );

```

<a id="ckeditor5/latest/updating/migrations/angular.html--step-4-optional-clean-up-the-document-head-entries-before-each-test">

#### Step 4 (Optional): Clean up the document head entries before each test

If you use a testing suite that does not clean up the document head entries before each test, you may need to do it manually. It is essential because the CKEditor 5 CDN script will inject the editor into the head section of your HTML file and, you need to ensure that the head section is clean before each test.

However, there is one downside to this approach. Cleaning up the head entries before each test may slow down the test execution because the browser needs to download the CKEditor 5 script each time. In most cases, this should not be a problem, but if you notice that your tests are running slower, you may need to consider other solutions.

Here is an example of how you can Clean up the document head entries before each test:

```
import { removeAllCkCdnResources } from '@ckeditor/ckeditor5-integrations-common/test-utils';

beforeEach( () => {
    removeAllCkCdnResources();
} );

```

<a id="ckeditor5/latest/updating/migrations/react.html">source file: "ckeditor5/latest/updating/migrations/react.html"</a>

## Migrating CKEditor 5 React integration from npm to CDN

This guide will help you migrate CKEditor 5 React integration from an NPM-based installation to a CDN-based one.

<a id="ckeditor5/latest/updating/migrations/react.html--prerequisites">

### Prerequisites

Remove the existing CKEditor 5 packages from your project. If you are using the NPM-based installation, you can remove it by running the following command:

```
npm uninstall ckeditor5 ckeditor5-premium-features

```

Upgrade the CKEditor 5 React integration to the latest version. You can find the latest version in the [React integration](#ckeditor5/latest/getting-started/installation/cloud/react/react-default-cdn.html) documentation.

Ensure that your testing suite uses real web browser environments for testing. If you are using `jsdom` or any other environment without a real DOM, you may need to adjust the testing suite configuration to use a real browser because CDN script injection might not be recognized properly in such environments.

<a id="ckeditor5/latest/updating/migrations/react.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/migrations/react.html--migrate-ckeditor-component">

#### Migrate `CKEditor` component

<a id="ckeditor5/latest/updating/migrations/react.html--step-1-remove-ckeditor-5-imports">

##### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your test files, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/react.html--step-2-use-useckeditorcloud-hook-to-load-ckeditor-5-from-cdn">

##### Step 2: Use `useCKEditorCloud` hook to load CKEditor 5 from CDN

The `useCKEditorCloud` function is a hook that allows you to load CKEditor 5 from the CDN. It returns an object with the `CKEditor` and `CKEditorPremiumFeatures` properties. Here is an example of migrating the basic CKEditor 5 React component:

**Before:**

```
import { CKEditor } from '@ckeditor/ckeditor5-react';
import { ClassicEditor, Bold, Essentials, Italic, Mention, Paragraph, Undo } from 'ckeditor5';
import { SlashCommand } from 'ckeditor5-premium-features';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

function App() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                toolbar: {
                    items: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                },
                plugins: [
                    Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo
                ],
                mention: {
                    // Mention configuration
                },
                root: {
                    initialData: '<p>Hello from CKEditor 5 in React!</p>'
                }
            } }
        />
    );
}

export default App;

```

**After:**

```
import { CKEditor, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

function App() {
    // Load CKEditor 5 from the CKEditor Cloud, using the `useCKEditorCloud` hook.
    // It'll inject the CKEditor 5 scripts and styles into your document head and after
    // successful loading, it'll return the `CKEditor` and `CKEditorPremiumFeatures` objects.
    const cloud = useCKEditorCloud( {
        version: '48.0.0', // Required. The version of CKEditor 5 to load.
        premium: true // Optional. Set to `true` if you want to use premium features.
    } );

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    if ( cloud.status === 'error' ) {
        console.error( cloud.error );

        return <div>Error!</div>;
    }

    // Pick the CKEditor 5 plugins you want to use.
    const {
        ClassicEditor, Bold, Essentials, Italic,
        Mention, Paragraph, SlashCommand, Undo
    } = cloud.CKEditor;

    const { SlashCommand } = cloud.CKEditorPremiumFeatures;

    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                toolbar: {
                    items: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                },
                plugins: [
                    Bold,
                    Essentials,
                    Italic,
                    Mention,
                    Paragraph,
                    SlashCommand,
                    Undo
                ],
                licenseKey: '<YOUR_LICENSE_KEY>',
                root: {
                    initialData: '<p>Hello from CKEditor 5 in React!</p>'
                }
            } }
        />
    );
}

```

<a id="ckeditor5/latest/updating/migrations/react.html--step-3-optional-migrate-the-ckeditor-5-react-testing-suite">

##### Step 3 (Optional): Migrate the CKEditor 5 React testing suite

If you have any tests that use CKEditor 5 objects, you need to update them to use the `loadCKEditorCloud` function. Here is an example of migrating a test that uses the `ClassicEditor` object:

**Before:**

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

it( 'ClassicEditor test', () => {
    render(
        <CKEditor
            editor={ ClassicEditor }
            // ... other props
        />
    );
} );

```

**After:**

```
// It may be counterintuitive that in tests you need to use `loadCKEditorCloud` instead of `useCKEditorCloud`.
// The reason for this is that `useCKEditorCloud` is a React hook and can only be used in React components,
// while tests are typically written as functions in testing suites. Therefore, in tests, you should use
// the `loadCKEditorCloud` function to load CKEditor 5 from the CKEditor Cloud and obtain the necessary
// CKEditor 5 objects. This allows you to properly test your CKEditor 5 integration without any issues.

import { loadCKEditorCloud } from '@ckeditor/ckeditor5-react';

let cloud;

beforeEach( async () => {
    cloud = await loadCKEditorCloud( {
        version: '48.0.0',
    } );
} );

it( 'ClassicEditor test', () => {
    const { ClassicEditor } = cloud.CKEditor;

    render(
        <CKEditor
            editor={ ClassicEditor }
            // ... other props
        />
    );

    // Rest of your test.
} );

```

<a id="ckeditor5/latest/updating/migrations/react.html--step-4-optional-clean-up-the-document-head-entries-before-each-test">

##### Step 4 (Optional): Clean up the document head entries before each test

The `useCKEditorCloud` hook under the hood injects the CKEditor 5 scripts and styles into your document head. If you use a testing suite that does not Clean up the document head entries before each test, you may need to do it manually. This is important because the `useCKEditorCloud` hook might reuse the same head entries for each test, which can lead to skipping the `loading` state and directly going to the `success` state. It may cause some tests that rely on the `loading` state to fail.

However, there is one downside to this approach. Cleaning up the head entries before each test may slow down the test execution because the browser needs to download the CKEditor 5 script each time. In most cases, this should not be a problem, but if you notice that your tests are running slower, you may need to consider other solutions.

Here is an example of how you can Clean up the document head entries before each test:

```
import { removeAllCkCdnResources } from '@ckeditor/ckeditor5-integrations-common/test-utils';

beforeEach( () => {
    removeAllCkCdnResources();
} );

```

The code above will remove all CKEditor 5 CDN scripts, style sheets, and Window objects from the head section of your HTML file before each test, making sure that the `useCKEditorCloud` hook will inject the CKEditor 5 scripts and styles again.

<a id="ckeditor5/latest/updating/migrations/react.html--migrate-ckeditorcontext-component">

#### Migrate `CKEditorContext` component

<a id="ckeditor5/latest/updating/migrations/react.html--step-1-remove-ckeditor-5-imports-2">

##### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your test files, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/react.html--step-2-use-useckeditorcloud-hook-to-load-ckeditor-5-context-from-cdn">

##### Step 2: Use `useCKEditorCloud` hook to load CKEditor 5 Context from CDN

If you use the `CKEditorContext` component, you need to update it to use the `useCKEditorCloud` hook. Here is an example of migrating the `CKEditorContext` component:

**Before:**

```
import { ClassicEditor, Context, Bold, Essentials, Italic, Paragraph, ContextWatchdog } from 'ckeditor5';
import { CKEditor, CKEditorContext } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

function App() {
  return (
    <CKEditorContext context={ Context } contextWatchdog={ ContextWatchdog }>
      <CKEditor
        editor={ ClassicEditor }
        config={ {
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        } }
        data='<p>Hello from the first editor working with the context!</p>'
        onReady={ ( editor ) => {
            // You can store the "editor" and use when it is needed.
            console.log( 'Editor 1 is ready to use!', editor );
        } }
      />

      <CKEditor
        editor={ ClassicEditor }
        config={ {
            licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        } }
        data='<p>Hello from the second editor working with the context!</p>'
        onReady={ ( editor ) => {
            // You can store the "editor" and use when it is needed.
            console.log( 'Editor 2 is ready to use!', editor );
        } }
      />
    </CKEditorContext>
  );
}

export default App;

```

**After:**

```
import { CKEditor, CKEditorContext, useCKEditorCloud } from '@ckeditor/ckeditor5-react';

function App() {
    // Load CKEditor 5 from the CKEditor Cloud, using the `useCKEditorCloud` hook.
    // It'll inject the CKEditor 5 scripts and styles into your document head and after
    // successful loading, it'll return the `CKEditor` and `CKEditorPremiumFeatures` objects.
    const cloud = useCKEditorCloud( {
        version: '48.0.0', // Required. The version of CKEditor 5 to load.
        premium: true // Optional. Set to `true` if you want to use premium features.
    } );

    if ( cloud.status === 'loading' ) {
        return <div>Loading...</div>;
    }

    if ( cloud.status === 'error' ) {
        console.error( cloud.error );

        return <div>Error!</div>;
    }

    // Pick the CKEditor 5 plugins you want to use.
    const {
        ClassicEditor, Bold, Essentials, Italic, Paragraph,
        Context, ContextWatchdog
    } = cloud.CKEditor;

    return (
        <CKEditorContext
            context={ Context }
            contextWatchdog={ ContextWatchdog }
        >
            <CKEditor
                editor={ ClassicEditor }
                config={ {
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Paragraph ],
                    toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                } }
                data='<p>Hello from the first editor working with the context!</p>'
                onReady={ ( editor ) => {
                    // You can store the "editor" and use when it is needed.
                    console.log( 'Editor 1 is ready to use!', editor );
                } }
            />

            <CKEditor
                editor={ ClassicEditor }
                config={ {
                    licenseKey: '<YOUR_LICENSE_KEY>',
                    plugins: [ Essentials, Bold, Italic, Paragraph ],
                    toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                } }
                data='<p>Hello from the second editor working with the context!</p>'
                onReady={ ( editor ) => {
                    // You can store the "editor" and use when it is needed.
                    console.log( 'Editor 2 is ready to use!', editor );
                } }
            />
        </CKEditorContext>
    );
}

```

<a id="ckeditor5/latest/updating/migrations/react.html--next-steps">

##### Next steps

Now that you have migrated your CKEditor 5 React Context integration to use the CDN, you can continue with the next steps, such as the migration testing suite. It is identical to the steps described in the previous section.

<a id="ckeditor5/latest/updating/migrations/react.html--migrate-usemultirooteditor-hook">

#### Migrate `useMultiRootEditor` hook

<a id="ckeditor5/latest/updating/migrations/react.html--step-1-remove-ckeditor-5-imports-3">

##### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your test files, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/react.html--step-2-use-withckeditorcloud-hoc-to-load-ckeditor-5-from-cdn">

##### Step 2: Use `withCKEditorCloud` HOC to load CKEditor 5 from CDN

If you use the `useMultiRootEditor` hook, you need to update it to use the `withCKEditorCloud` HOC. Here is an example of migrating the `useMultiRootEditor` hook:

**Before:**

```
import { MultiRootEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { useMultiRootEditor } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

const App = () => {
    const editorProps = {
        editor: MultiRootEditor,
        data: {
            intro: '<h1>React multi-root editor</h1>',
            content: '<p>Hello from CKEditor&nbsp;5 multi-root!</p>'
        },
        config: {
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: {
                items: [ 'undo', 'redo', '|', 'bold', 'italic' ]
            },
        }
    };

    const {
        editor,
        toolbarElement,
        editableElements,
        data,
        setData,
        attributes,
        setAttributes
    } = useMultiRootEditor( editorProps );

    return (
        <div className="App">
            { toolbarElement }
            { editableElements }
        </div>
    );
}

export default App;

```

**After:**

```
import { withCKEditorCloud } from '@ckeditor/ckeditor5-react';

/**
 * The `withCKEditorCloud` HOC allows you to load CKEditor 5 from the CKEditor Cloud and inject loaded data
 * as `cloud` property into your component. Configuration of the `cloud` passed to `withCKEditorCloud` is
 * the same as for the `useCKEditorCloud` hook and you can specify the version of CKEditor 5 to load and
 * optionally enable premium features.
 */
const withCKCloud = withCKEditorCloud( {
    cloud: {
        version: '43.0.0',
        languages: [ 'en', 'de' ]
    },

    // Optional. Render error when loading CKEditor 5 from the CKEditor Cloud fails.
    renderError: ( error ) => {
        console.error( error );

        return <div>Error!</div>;
    },

    // Optional: Render loading state when CKEditor 5 is being loaded from the CKEditor Cloud.
    renderLoader: () => <div>Loading...</div>,
} );

const App = withCKCloud( ( { cloud } ) => {
    const {
        MultiRootEditor,
        Bold,
        Essentials,
        Italic,
        Paragraph
    } = cloud.CKEditor;

    const editorProps = {
        editor: MultiRootEditor,
        data: {
            intro: '<h1>React multi-root editor</h1>',
            content: '<p>Hello from CKEditor&nbsp;5 multi-root!</p>'
        },
        config: {
            plugins: [ Essentials, Bold, Italic, Paragraph ],
            toolbar: {
                items: [ 'undo', 'redo', '|', 'bold', 'italic' ]
            },
        }
    };

    const {
        editor,
        toolbarElement,
        editableElements,
        data,
        setData,
        attributes,
        setAttributes
    } = useMultiRootEditor( editorProps );

    return (
        <div className="App">
            { toolbarElement }
            { editableElements }
        </div>
    );
} );

```

<a id="ckeditor5/latest/updating/migrations/testing-suite.html">source file: "ckeditor5/latest/updating/migrations/testing-suite.html"</a>

## Migrating CKEditor 5 testing suite from npm to CDN

This guide will help you migrate the CKEditor 5 testing suite from an NPM-based installation to a CDN-based one.

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--prerequisites">

### Prerequisites

Ensure that your testing suite uses real web browser environments for testing. If you are using `jsdom` or any other environment without a real DOM, you may need to adjust the testing suite configuration to use a real browser because CDN script injection might not be recognized properly in such environments.

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--step-1-remove-ckeditor-5-imports">

#### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your test files, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--step-2-update-your-test-files-to-use-cdn">

#### Step 2: Update your test files to use CDN

**Before:**

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';

it( 'ClassicEditor test', () => {
    // Your test that use CKEditor 5 object.
} );

```

**After:**

```
import { loadCKEditorCloud } from '@ckeditor/ckeditor5-integrations-common';

let cloud;

beforeEach( async () => {
    cloud = await loadCKEditorCloud( {
        version: '48.0.0',
    } );
} );

it( 'ClassicEditor test', () => {
    const { ClassicEditor } = cloud;

    // Your test that use CKEditor 5 object.
} );

```

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--step-3-optional-clean-up-the-document-head-entries-before-each-test">

#### Step 3 (Optional): Clean up the document head entries before each test

If you use a testing suite that does not clean up the document head entries before each test, you may need to do it manually. It is essential because the CKEditor 5 CDN script will inject the editor into the head section of your HTML file, and you need to ensure that the head section is clean before each test.

However, there is one downside to this approach. Cleaning up the head entries before each test may slow down the test execution because the browser needs to download the CKEditor 5 script each time. In most cases, this should not be a problem, but if you notice that your tests are running slower, you may need to consider other solutions.

Here is an example of how you can clean up the document head entries before each test:

```
import { removeAllCkCdnResources } from '@ckeditor/ckeditor5-integrations-common/test-utils';

beforeEach( () => {
    removeAllCkCdnResources();
} );

```

The code above will remove all CKEditor 5 CDN scripts, style sheets, and Window objects from the head section of your HTML file before each test.

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--known-issues">

### Known issues

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--slow-test-execution">

#### Slow test execution

If you notice that your tests are running slower after migrating to CDN, it may be caused by the browser downloading the CKEditor 5 script each time the test is executed. While it is not recommended to disable the head cleanup before each test, you may disable it if you notice a significant slowdown in your test execution and your code handles the CKEditor 5 script async injection properly.

<a id="ckeditor5/latest/updating/migrations/testing-suite.html--script-injection-issues">

#### Script injection issues

If you notice that the CKEditor 5 script is not injected properly, ensure that your testing suite uses a real browser environment for testing. If you use `jsdom` or any other environment without a real DOM, you may need to adjust the testing suite configuration to use a real browser. Consider using tools like:

* [Vitest](https://vitest.dev/)
* [Playwright](https://playwright.dev/)
* [Cypress](https://www.cypress.io/)

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html">source file: "ckeditor5/latest/updating/migrations/vanilla-js.html"</a>

## Migrating CKEditor 5 from npm to CDN

This guide will help you migrate CKEditor 5 from an NPM-based installation to a CDN-based one. CDN-based installations can simplify the setup process by providing a bundler-agnostic way to lazy initialization of CKEditor 5 scripts and styles injection. It reduces complexity in the project setup.

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--prerequisites">

### Prerequisites

If you use frameworks like [Laravel](https://laravel.com/), [Symfony](https://symfony.com/), or [Ruby on Rails](https://rubyonrails.org/), modify the head section in the main layout file and follow the traditional HTML integration to install CKEditor 5.

However, if you use SPA frameworks like [React](https://reactjs.org/), [Angular](https://angular.io/), [Vue.js](https://vuejs.org/), or [Svelte](https://svelte.dev/) and do not use official integrations, you may need to follow different steps to migrate CKEditor 5 from npm to CDN. In this case, you can utilize the lazy injection of CKEditor 5 since you cannot directly modify the head section.

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--traditional-html-integration">

### Traditional HTML integration

The traditional HTML integration to installing CKEditor 5 involves modification of the HTML head section to include the CKEditor 5 script from the CDN. The editor is then initialized using the `window.CKEDITOR` global variable.

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--step-1-update-your-html-file">

#### Step 1: Update your HTML file

First, update your HTML file to include the CKEditor 5 script from the CDN. Add the following script and style sheet tag inside the `<head>` section of your HTML file:

```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CKEditor 5 CDN Example</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css">
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js"></script>

    <!-- Optionally, add premium features. -->
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5-premium-features.css">
    <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5-premium-features.js"></script>
</head>
<body>
    <textarea name="content" id="editor"></textarea>
    <script src="app.js"></script>
</body>
</html>

```

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--step-2-replace-ckeditor-5-imports-with-windowckeditor">

#### Step 2: Replace CKEditor 5 imports with `window.CKEDITOR`

Since the CKEditor 5 script is now included via the CDN, you can access the `ClassicEditor` object directly in your JavaScript file using the `window.CKEDITOR` global variable. It means that `import` statements are no longer needed and you can remove them from your JavaScript files. Here is an example of migrating the CKEditor 5 initialization code:

**Before:**

```
import { ClassicEditor } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

ClassicEditor
    .create( {
        attachTo: document.querySelector('#editor'),
        licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
        // ... other configuration
    } )
    .catch( error => {
        console.error(error);
    } );

```

**After:**

```
const { ClassicEditor } = window.CKEDITOR;
const { AIAdapter, /* ... other imports */ } = window.CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( {
        attachTo: document.querySelector('#editor'),
        licenseKey: '<YOUR_LICENSE_KEY>',
        // ... other configuration
    } )
    .catch( error => {
        console.error(error);
    } );

```

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--using-lazy-injection-of-ckeditor-5">

### Using lazy injection of CKEditor 5

If you prefer to automatically inject the CKEditor 5 script into your HTML file, you can migrate your project using the `@ckeditor/ckeditor5-integrations-common` package. This package provides a `loadCKEditorCloud` function that automatically injects the CKEditor 5 scripts and styles into your HTML file. It may be useful when your project uses a bundler like Webpack or Rollup and you cannot modify your head section directly.

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--step-1-install-the-ckeditorckeditor5-integrations-common-package">

#### Step 1: Install the `@ckeditor/ckeditor5-integrations-common` Package

First, install the `@ckeditor/ckeditor5-integrations-common` package using the following command:

```
npm install @ckeditor/ckeditor5-integrations-common

```

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--step-2-replace-ckeditor-5-imports">

#### Step 2: Replace CKEditor 5 Imports

If you have any CKEditor 5 imports in your JavaScript files, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

Next, update your JavaScript file to use the `loadCKEditorCloud` function from the `@ckeditor/ckeditor5-integrations-common` package. Here is an example of migrating the CKEditor 5 initialization code:

**Before:**

```
import { ClassicEditor } from 'ckeditor5';

ClassicEditor
    .create( {
        attachTo: document.querySelector('#editor')
    } )
    .catch( error => {
        console.error(error);
    } );

```

**After:**

```
import { loadCKEditorCloud } from '@ckeditor/ckeditor5-integrations-common';

const { ClassicEditor } = await loadCKEditorCloud( {
    version: '48.0.0',
} );

```

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--migrating-custom-plugins">

### Migrating custom plugins

If you are using custom plugins, you need to first [adapt these to work with the CDN approach](#ckeditor5/latest/framework/tutorials/creating-simple-plugin-timestamp.html--adapt-this-tutorial-to-cdn). It will change the way imports and CSS files are handled.

Next, refer to the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html) guide to learn about using the [loadCKEditorCloud](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--using-the-useckeditorcloud-function) function. This will be needed to include the custom plugin in the CDN configuration of CKEditor 5\. By employing these, you can dynamically import the plugin in a way similar to this one:

```
plugins: {
  CustomPlugin: () => import('./path/to/plugin.umd.js')
}

```

If your plugin depends on core plugins already loaded via CDN, you can access them through the `window.CKEDITOR` and `window.CKEDITOR_PREMIUM_FEATURES` global variables.

Also, `loadCKEditorCloud` uses caching, so you can call it to dynamically load dependencies. Find more details in the options section of the [Loading CDN resources](#ckeditor5/latest/getting-started/setup/loading-cdn-resources.html--the-loadckeditorcloud-function-options) guide.

<a id="ckeditor5/latest/updating/migrations/vanilla-js.html--conclusion">

### Conclusion

Following these steps, you successfully migrated CKEditor 5 from an NPM-based installation to a CDN-based installation using Vanilla JS. This approach simplifies the setup process and can help improve the performance of your application by reducing the bundle size.

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html">source file: "ckeditor5/latest/updating/migrations/vuejs-v3.html"</a>

## Migrating Vue.js 3+ CKEditor 5 integration from npm to CDN

This guide will help you migrate Vue 3 CKEditor 5 integration from an NPM-based installation to a CDN-based one.

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--prerequisites">

### Prerequisites

Remove the existing CKEditor 5 packages from your project. If you are using the NPM-based installation, you can remove it by running the following command:

```
npm uninstall ckeditor5 ckeditor5-premium-features

```

Upgrade the CKEditor 5 Vue 3 integration to the latest version. You can find the latest version in the [Vue 3 integration](#ckeditor5/latest/getting-started/installation/cloud/vuejs-v3.html) documentation.

Ensure that your testing suite uses real web browser environments for testing. If you are using `jsdom` or any other environment without a real DOM, you may need to adjust the testing suite configuration to use a real browser because CDN script injection might not be recognized properly in such environments.

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--step-1-remove-ckeditor-5-imports">

#### Step 1: Remove CKEditor 5 imports

If you have any CKEditor 5 imports in your Vue components, remove them. For example, remove lines like:

```
import { ClassicEditor, /* ... other imports */  } from 'ckeditor5';
import { AIAdapter, /* ... other imports */ } from 'ckeditor5-premium-features';

```

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--step-2-update-your-vue-components-to-use-cdn">

#### Step 2: Update your Vue components to use CDN

Replace the CKEditor 5 NPM package imports with the CDN script imports and use the `useCKEditorCloud` function to load the CKEditor 5 scripts. The `useCKEditorCloud` function is a part of the `@ckeditor/ckeditor5-vue` package and is used to load CKEditor 5 scripts from the CKEditor Cloud service.

**Before:**

```
<template>
    <h2>Using CKEditor 5 from NPM in Vue 3</h2>

    <ckeditor
        v-model="data"
        tag-name="textarea"
        :editor="TestEditor"
        :config="config"
    />
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue';
import {
    ClassicEditor,
    Essentials,
    Paragraph,
    Heading,
    Bold,
    Italic,
    type EventInfo
} from 'ckeditor5';

class TestEditor extends ClassicEditor {
    static builtinPlugins = [
        Essentials,
        Paragraph,
        Heading,
        Bold,
        Italic
    ];
}

const data = ref( '<p>Hello world!</p>' );
const config = reactive( {
    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
    toolbar: [ 'heading', '|', 'bold', 'italic' ]
} );
</script>

```

**After:**

```
<template>
    <h2>Using CKEditor 5 from NPM in Vue 3</h2>
      <ckeditor
        v-if="TestEditor"
        v-model="data"
        tag-name="textarea"
        :editor="TestEditor"
        :config="config"
    />
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue';
import { useCKEditorCloud } from '@ckeditor/ckeditor5-vue';

const cloud = useCKEditorCloud( {
    version: '48.0.0'
} );

const TestEditor = computed( () => {
    if ( !cloud.data.value ) {
        return null;
    }

    const {
        ClassicEditor: BaseEditor, Paragraph,
        Essentials, Heading, Bold, Italic
    } = cloud.data.value.CKEditor;

    return class TestEditor extends BaseEditor {
        static builtinPlugins = [
            Essentials,
            Paragraph,
            Heading,
            Bold,
            Italic
        ];
    };
} );

const data = ref( '<p>Hello world!</p>' );
const config = reactive( {
    licenseKey: '<YOUR_LICENSE_KEY>',
    toolbar: [ 'heading', '|', 'bold', 'italic' ]
} );
</script>

```

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--step-3-optional-migrate-the-ckeditor-5-vue-3-integration-testing-suite">

#### Step 3 (Optional): Migrate the CKEditor 5 Vue 3+ integration testing suite

If you have any tests that use CKEditor 5 objects, you need to update them to use the `loadCKEditorCloud` function. Here is an example of migrating a test that uses the `ClassicEditor` object:

**Before:**

```
import { ClassicEditor, /* ... other imports */ } from 'ckeditor5';

it( 'ClassicEditor test', () => {
    // Your test that uses the CKEditor 5 object.
} );

```

**After:**

```
// It may be counterintuitive that in tests you need to use `loadCKEditorCloud` instead of `useCKEditorCloud`.
// The reason for this is that `useCKEditorCloud` is composable and can only be used in Vue components,
// while tests are typically written as functions in testing suites. Therefore, in tests, you should use
// the `loadCKEditorCloud` function to load CKEditor 5 from the CKEditor Cloud and obtain the necessary
// CKEditor 5 objects. This allows you to properly test your CKEditor 5 integration without any issues.

import { loadCKEditorCloud } from '@ckeditor/ckeditor5-vue';

let cloud;

beforeEach( async () => {
    cloud = await loadCKEditorCloud( {
        version: '48.0.0',
    } );
} );

it( 'ClassicEditor test', () => {
    const { ClassicEditor, ... } = cloud.CKEditor;

    // Your test that uses the CKEditor 5 object.
} );

```

<a id="ckeditor5/latest/updating/migrations/vuejs-v3.html--step-4-optional-clean-up-the-document-head-entries-before-each-test">

#### Step 4 (Optional): Clean up the document head entries before each test

The `useCKEditorCloud` composable under the hood injects the CKEditor 5 scripts and styles into your document head. If you use a testing suite that does not Clean up the document head entries before each test, you may need to do it manually. This is important because the `useCKEditorCloud` composable might reuse the same head entries for each test, which can lead to skipping the `loading` state and directly going to the `success` state. It may cause some tests that rely on the `loading` state to fail.

However, there is one downside to this approach. Cleaning up the head entries before each test may slow down the test execution because the browser needs to download the CKEditor 5 script each time. In most cases, this should not be a problem, but if you notice that your tests are running slower, you may need to consider other solutions.

Here is an example of how you can Clean up the document head entries before each test:

```
import { removeAllCkCdnResources } from '@ckeditor/ckeditor5-integrations-common/test-utils';

beforeEach( () => {
    removeAllCkCdnResources();
} );

```

The code above will remove all CKEditor 5 CDN scripts, style sheets, and Window objects from the head section of your HTML file before each test, making sure that the `useCKEditorCloud` composable will inject the CKEditor 5 scripts and styles again.

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html">source file: "ckeditor5/latest/updating/nim-migration/custom-plugins.html"</a>

## Migrating custom plugins

If you have created and published custom plugins for CKEditor 5, you will need to adjust them to make them work with the new installation methods.

You do not need to follow this guide if your custom plugins are used directly in your project and are not separate packages. In such cases, you can update the plugins along with the projects that use them.

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--prerequisites">

### Prerequisites

Before you start, follow the usual upgrade path to update your plugin to use the latest version of CKEditor 5\. This will rule out any problems that may be caused by upgrading from an outdated version of CKEditor 5.

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--create-a-new-project-using-the-package-generator">

#### Create a new project using the package generator

To ensure that all the dependencies are up-to-date and that the build process is correct, we recommend the following steps:

1. Create a new project using the package generator following the [package generator guide](#ckeditor5/latest/framework/develpment-tools/package-generator/using-package-generator.html).
2. Copy the `src`, `tests`, and `sample` folders of your plugin into the new project.
3. Re-add all the external `dependencies`, `devDependencies`, and `peerDependencies` specific to your plugin to the `package.json` file.

When you run the CLI, it generates the modern build setup and the imports used across the new ecosystem.

The main changes we have introduced in the new package generator are:

* Making the generated package a valid ECMAScript module,
* Updating the build process to generate bundles for the new installation methods,
* Adding new eslint rules to avoid common errors,
* Updating dependencies.

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--add-missing-file-extensions-in-imports">

#### Add missing file extensions in imports

Next, as required by the JavaScript modules (ESM), you must add the missing file extensions to all files in the `src`, `tests`, and `sample` folders during import.

```
- import { Plugin } from 'ckeditor5/src/core';
+ import { Plugin } from 'ckeditor5';

-import SomePlugin from './src/someplugin';
+import SomePlugin from './src/someplugin.js';

```

Imports from the package roots should be changed to `ckeditor5`.

```
- import { Plugin } from '@ckeditor/ckeditor5-core';
+ import { Plugin } from 'ckeditor5';

```

If you run the following command, the `ckeditor5-rules/require-file-extensions-in-imports` eslint rule should fix most, if not all, problems related to missing file extensions.

```
npm run lint -- --fix

```

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--remove-src-folders-from-the-import-paths">

#### Remove `src` folders from the import paths

For some time now, we have strongly discouraged importing from the `src` folder of the `@ckeditor/ckeditor5-*` packages. Instead, you should import from the package roots because they provide better TypeScript support and because the `src` folders are now removed. Always import from the `ckeditor5`.

```
// ❌
import Plugin from '@ckeditor/ckeditor5-core/src/plugin.js';

// ❌
import { Plugin } from '@ckeditor/ckeditor5-core';

// ✅
import { Plugin } from 'ckeditor5';

```

Note that the names of the exports may differ between the `src` folder and the package root. In the above example, the named `Plugin` import from `@ckeditor/ckeditor5-core/src/plugin.js` will be exported under the same name from `ckeditor5`, but this is not guaranteed. In cases where the names do not match, you will need to modify the import accordingly.

There may also be cases where something you imported from the `src` folder is not exported from the package root. In such cases, please create a new issue in the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues/new/choose) so we can consider adding the missing exports.

If you run the following command, the `ckeditor5-rules/allow-imports-only-from-main-package-entry-point` eslint rule will list all the places where you need to update the imports.

```
npm run lint

```

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--remove-theme-folders-from-the-import-paths">

#### Remove `theme` folders from the import paths

The same rule applies to the `theme` folder in the `@ckeditor/ckeditor5-*` packages. If you need to use icons from this folder, you can likely import them from the package root.

```
// ❌
import undo from '@ckeditor/ckeditor5-icons/theme/undo.svg';

console.log( undo );

// ✅
import { IconUndo } from 'ckeditor5';

console.log( IconUndo );

```

If you run the following command, the `ckeditor5-rules/allow-imports-only-from-main-package-entry-point` eslint rule will list all the places where you need to update the imports.

```
npm run lint

```

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--update-imports-to-the-ckeditor5-package">

#### Update imports to the `ckeditor5` package

Update all imports from `ckeditor5/src/*` and `@ckeditor/ckeditor5-*` to `ckeditor5`.

```
- import { Plugin } from 'ckeditor5/src/core.js';
- import { ButtonView } from 'ckeditor5/src/ui.js';
+ import { Plugin, ButtonView } from 'ckeditor5';

```

If you run the following command, the `ckeditor5-rules/no-legacy-imports` eslint rule will list all the places where you need to update the imports.

```
npm run lint

```

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--run-eslint">

#### Run eslint

Run the `npm run lint` command to see if there are any remaining problems that need to be fixed.

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--generate-and-validate-the-bundle">

### Generate and validate the bundle

Once you have updated all the imports, it is time to build and validate the bundle for the new installation methods.

1. Build the plugin with the following command. It will create the `dist` folder with the plugin bundles for the new installation methods.  
```  
npm run build  
```
2. Inspect the imports at the top of the `dist/index.js` file. You should only see imports from `ckeditor5` (not from `ckeditor5/src/*`) and optionally from other external dependencies.
3. Repeat the above step for the `dist/browser/index.es.js` file, but this time you should only see imports from `ckeditor5` or `ckeditor5-premium-features`. All other imports, including external dependencies, should be bundled with the plugin.

If you see imports in the second or third step that are not explicitly mentioned, check where the imports come from in the source code and if they have been updated according to the above migration steps. If this is the case and the imports in the generated bundle are still incorrect, please create a new issue in the [CKEditor 5 repository](https://github.com/ckeditor/ckeditor5/issues/new/choose).

<a id="ckeditor5/latest/updating/nim-migration/custom-plugins.html--how-to-use-your-plugin-in-new-installation-methods">

### How to use your plugin in new installation methods?

Once the package is migrated, follow the [Build output and integration](#ckeditor5/latest/framework/develpment-tools/package-generator/build-output-and-integration.html) guide to integrate it with npm, ZIP, or CDN setups.

<a id="ckeditor5/latest/updating/nim-migration/customized-builds.html">source file: "ckeditor5/latest/updating/nim-migration/customized-builds.html"</a>

## Migrating from customized builds

Migrating from a customized build to the new installation methods should mostly be a matter of changing the way you import CKEditor 5 and its plugins.

Regardless of whether you used our old Online Builder or created a custom build from source using webpack or Vite, the new installation methods allow you to build and run the editor with any bundler or JavaScript meta-framework you like. This means that by the end of the migration, you can remove the CKEditor-specific webpack or Vite setup from your project if you already use another bundler to build your project.

<a id="ckeditor5/latest/updating/nim-migration/customized-builds.html--prerequisites">

### Prerequisites

Before you start, follow the usual upgrade path to update your project to use the latest version of CKEditor 5\. This will rule out any problems that may be caused by upgrading from an outdated version of the editor.

<a id="ckeditor5/latest/updating/nim-migration/customized-builds.html--migration-steps">

### Migration steps

If you are using the customized build, follow the steps below:

1. Start by uninstalling all CKEditor 5 packages that you have installed in your project. This includes the main `ckeditor5` package and any additional plugins that you have installed separately.  
```  
npm uninstall \  
    @ckeditor/ckeditor5-adapter-ckfinder \  
    @ckeditor/ckeditor5-alignment \  
    @ckeditor/ckeditor5-autoformat \  
    @ckeditor/ckeditor5-autosave \  
    @ckeditor/ckeditor5-basic-styles \  
    @ckeditor/ckeditor5-block-quote \  
    @ckeditor/ckeditor5-ckbox \  
    @ckeditor/ckeditor5-ckfinder \  
    @ckeditor/ckeditor5-clipboard \  
    @ckeditor/ckeditor5-cloud-services \  
    @ckeditor/ckeditor5-code-block \  
    @ckeditor/ckeditor5-core \  
    @ckeditor/ckeditor5-easy-image \  
    @ckeditor/ckeditor5-editor-balloon \  
    @ckeditor/ckeditor5-editor-classic \  
    @ckeditor/ckeditor5-editor-decoupled \  
    @ckeditor/ckeditor5-editor-inline \  
    @ckeditor/ckeditor5-editor-multi-root \  
    @ckeditor/ckeditor5-engine \  
    @ckeditor/ckeditor5-enter \  
    @ckeditor/ckeditor5-essentials \  
    @ckeditor/ckeditor5-find-and-replace \  
    @ckeditor/ckeditor5-font \  
    @ckeditor/ckeditor5-heading \  
    @ckeditor/ckeditor5-highlight \  
    @ckeditor/ckeditor5-horizontal-line \  
    @ckeditor/ckeditor5-html-embed \  
    @ckeditor/ckeditor5-html-support \  
    @ckeditor/ckeditor5-image \  
    @ckeditor/ckeditor5-indent \  
    @ckeditor/ckeditor5-language \  
    @ckeditor/ckeditor5-link \  
    @ckeditor/ckeditor5-list \  
    @ckeditor/ckeditor5-markdown-gfm \  
    @ckeditor/ckeditor5-media-embed \  
    @ckeditor/ckeditor5-mention \  
    @ckeditor/ckeditor5-minimap \  
    @ckeditor/ckeditor5-page-break \  
    @ckeditor/ckeditor5-paragraph \  
    @ckeditor/ckeditor5-paste-from-office \  
    @ckeditor/ckeditor5-remove-format \  
    @ckeditor/ckeditor5-restricted-editing \  
    @ckeditor/ckeditor5-select-all \  
    @ckeditor/ckeditor5-show-blocks \  
    @ckeditor/ckeditor5-source-editing \  
    @ckeditor/ckeditor5-special-characters \  
    @ckeditor/ckeditor5-style \  
    @ckeditor/ckeditor5-table \  
    @ckeditor/ckeditor5-theme-lark \  
    @ckeditor/ckeditor5-typing \  
    @ckeditor/ckeditor5-ui \  
    @ckeditor/ckeditor5-undo \  
    @ckeditor/ckeditor5-upload \  
    @ckeditor/ckeditor5-utils \  
    @ckeditor/ckeditor5-watchdog \  
    @ckeditor/ckeditor5-widget \  
    @ckeditor/ckeditor5-word-count \  
    @ckeditor/ckeditor5-ai \  
    @ckeditor/ckeditor5-case-change \  
    @ckeditor/ckeditor5-collaboration-core \  
    @ckeditor/ckeditor5-comments \  
    @ckeditor/ckeditor5-document-outline \  
    @ckeditor/ckeditor5-export-pdf \  
    @ckeditor/ckeditor5-export-word \  
    @ckeditor/ckeditor5-format-painter \  
    @ckeditor/ckeditor5-import-word \  
    @ckeditor/ckeditor5-list-multi-level \  
    @ckeditor/ckeditor5-pagination \  
    @ckeditor/ckeditor5-paste-from-office-enhanced \  
    @ckeditor/ckeditor5-real-time-collaboration \  
    @ckeditor/ckeditor5-revision-history \  
    @ckeditor/ckeditor5-slash-command \  
    @ckeditor/ckeditor5-template \  
    @ckeditor/ckeditor5-track-changes \  
    ckeditor5 \  
    ckeditor5-collaboration  
```
2. Next, install the `ckeditor5` package. This package contains the editor and all of our open-source plugins.  
```  
npm install ckeditor5  
```
3. (Optional) If you are using premium features from our commercial offer, you should also install the `ckeditor5-premium-features` package.  
```  
npm install ckeditor5-premium-features  
```
4. Open the file where you initialized the editor. Then, replace the import statements to import the editor and all the open-source plugins from the `ckeditor5` package and the commercial plugins from the `ckeditor5-premium-features` package only.  
```  
import { ClassicEditor, Essentials, Bold, Italic, Paragrap, Mention } from 'ckeditor5';  
import { FormatPainter, SlashCommand } from 'ckeditor5-premium-features';  
```
5. Below these imports, add imports of the CSS styles for the editor and the commercial plugins.  
```  
import 'ckeditor5/ckeditor5.css';  
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';  
```

<a id="ckeditor5/latest/updating/nim-migration/customized-builds.html--example">

### Example

Below is a comparison of the editor configuration before and after the migration.

Before 

```
import { ClassicEditor as ClassicEditorBase } from '@ckeditor/ckeditor5-editor-classic';

import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { CKFinderUploadAdapter } from '@ckeditor/ckeditor5-adapter-ckfinder';
import { Autoformat } from '@ckeditor/ckeditor5-autoformat';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote';
import { CKBox } from '@ckeditor/ckeditor5-ckbox';
import { CKFinder } from '@ckeditor/ckeditor5-ckfinder';
import { EasyImage } from '@ckeditor/ckeditor5-easy-image';
import { Heading } from '@ckeditor/ckeditor5-heading';
import { Image, ImageCaption, ImageStyle, ImageToolbar, ImageUpload, PictureEditing } from '@ckeditor/ckeditor5-image';
import { Indent } from '@ckeditor/ckeditor5-indent';
import { Link } from '@ckeditor/ckeditor5-link';
import { List } from '@ckeditor/ckeditor5-list';
import { MediaEmbed } from '@ckeditor/ckeditor5-media-embed';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { PasteFromOffice } from '@ckeditor/ckeditor5-paste-from-office';
import { Table, TableToolbar } from '@ckeditor/ckeditor5-table';
import { TextTransformation } from '@ckeditor/ckeditor5-typing';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services';

export default class ClassicEditor extends ClassicEditorBase {
    static builtinPlugins = [
        Essentials,
        CKFinderUploadAdapter,
        Autoformat,
        Bold,
        Italic,
        BlockQuote,
        CKBox,
        CKFinder,
        CloudServices,
        EasyImage,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        PictureEditing,
        Table,
        TableToolbar,
        TextTransformation
    ];

    static defaultConfig = {
        toolbar: {
            items: [
                'undo', 'redo',
                '|', 'heading',
                '|', 'bold', 'italic',
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'
            ]
        },
        image: {
            toolbar: [
                'imageStyle:inline',
                'imageStyle:block',
                'imageStyle:side',
                '|',
                'toggleImageCaption',
                'imageTextAlternative'
            ]
        },
        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        },
        language: 'en'
    };
}

```

After 

```
import {
    ClassicEditor as ClassicEditorBase,
    Essentials,
    CKFinderUploadAdapter,
    Autoformat,
    Bold,
    Italic,
    BlockQuote,
    CKBox,
    CKFinder,
    Heading,
    Image,
    ImageCaption,
    ImageStyle,
    ImageToolbar,
    ImageUpload,
    PictureEditing,
    Indent,
    Link,
    List,
    MediaEmbed,
    Paragraph,
    PasteFromOffice,
    Table,
    TableToolbar,
    TextTransformation,
    CloudServices
} from 'ckeditor5';

import 'ckeditor5/ckeditor5.css';

export default class ClassicEditor extends ClassicEditorBase {
    static builtinPlugins = [
        Essentials,
        CKFinderUploadAdapter,
        Autoformat,
        Bold,
        Italic,
        BlockQuote,
        CKBox,
        CKFinder,
        CloudServices,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        PictureEditing,
        Table,
        TableToolbar,
        TextTransformation
    ];

    static defaultConfig = {
        toolbar: {
            items: [
                'undo', 'redo',
                '|', 'heading',
                '|', 'bold', 'italic',
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'
            ]
        },
        image: {
            toolbar: [
                'imageStyle:inline',
                'imageStyle:block',
                'imageStyle:side',
                '|',
                'toggleImageCaption',
                'imageTextAlternative'
            ]
        },
        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        },
        language: 'en'
    };
}

```

<a id="ckeditor5/latest/updating/nim-migration/dll-builds.html">source file: "ckeditor5/latest/updating/nim-migration/dll-builds.html"</a>

## Migrating from DLL builds

DLLs are webpack-specific builds that register CKEditor 5 and its plugins in a globally scoped variable `CKEditor5`. This variable could then be used to create the editor instance.

Since the new installation methods do not rely on global variables, migrating from the DLL builds to the new installation methods should mostly be a matter of changing the way you import CKEditor 5 and its plugins.

Other notable difference is that DLLs use the `<script>` tags while the new CDN build uses the `<script type="module">` tag, which behave differently in some cases. For more information, see this [MDN page explaining the differences between modules and standard scripts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#other%5Fdifferences%5Fbetween%5Fmodules%5Fand%5Fstandard%5Fscripts).

<a id="ckeditor5/latest/updating/nim-migration/dll-builds.html--prerequisites">

### Prerequisites

Before you start, follow the usual upgrade path to update your project to use the latest version of CKEditor 5\. This will rule out any problems that may be caused by upgrading from an outdated version of the editor.

<a id="ckeditor5/latest/updating/nim-migration/dll-builds.html--migration-steps">

### Migration steps

If you are using the DLL build, follow the steps below:

1. Remove the `<script>` tags that load the CKEditor 5 DLL builds from your project.
2. Add the `<link>` tags to include the editor’s CSS files and the `<script type="importmap">` tag to map the package names to the build URLs.

2.1 If you only use the open-source editor:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<script type="importmap">  
{  
    "imports": {  
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",  
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"  
    }  
}  
</script>  
```

2.2 If you also use premium features from our commercial offer:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />  
<script type="importmap">  
{  
    "imports": {  
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",  
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",  
        "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.js",  
        "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/"  
    }  
}  
</script>  
```
3. Replace the old `<script>` tag that contains the initialization code with the `<script type="module">` tag. In it, you can import the editor and plugins from the `ckeditor5` and `ckeditor5-premium-features` packages instead of relying on the global `CKEditor5` variable.

3.1 If you only use the open-source editor:  
```  
<script type="module">  
import { ClassicEditor, Essentials, Bold, Italic, Paragraph } from 'ckeditor5';  
ClassicEditor.create( {  
    attachTo: document.querySelector( '#editor' ),  
    plugins: [ Essentials, Bold, Italic, Paragraph ],  
    toolbar: [ /* ... */ ]  
} );  
</script>  
```

3.2 If you also use premium features from our commercial offer:  
```  
<script type="module">  
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from 'ckeditor5';  
import { SlashCommand } from 'ckeditor5-premium-features';  
ClassicEditor.create( {  
    attachTo: document.querySelector( '#editor' ),  
    plugins: [ Essentials, Bold, Italic, Paragraph, Mention, SlashCommand ],  
    toolbar: [ /* ... */ ],  
    licenseKey: '<YOUR_LICENSE_KEY>',  
} );  
</script>  
```

<a id="ckeditor5/latest/updating/nim-migration/dll-builds.html--example">

### Example

Below is the comparison of the editor configuration before and after the migration.

Before 

```
<script src="path/to/node_modules/ckeditor5/build/ckeditor5-dll.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-editor-classic/build/editor-classic.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-autoformat/build/autoformat.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-basic-styles/build/basic-styles.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-block-quote/build/block-quote.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-essentials/build/essentials.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-heading/build/heading.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-image/build/image.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-indent/build/indent.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-link/build/link.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-list/build/list.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-media-embed/build/media-embed.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-paste-from-office/build/paste-from-office.js"></script>
<script src="path/to/node_modules/@ckeditor/ckeditor5-table/build/table.js"></script>

<script>
const config = {
    plugins: [
        CKEditor5.autoformat.Autoformat,
        CKEditor5.basicStyles.Bold,
        CKEditor5.basicStyles.Italic,
        CKEditor5.blockQuote.BlockQuote,
        CKEditor5.essentials.Essentials,
        CKEditor5.heading.Heading,
        CKEditor5.image.Image,
        CKEditor5.image.ImageCaption,
        CKEditor5.image.ImageStyle,
        CKEditor5.image.ImageToolbar,
        CKEditor5.image.ImageUpload,
        CKEditor5.indent.Indent,
        CKEditor5.link.Link,
        CKEditor5.list.List,
        CKEditor5.mediaEmbed.MediaEmbed,
        CKEditor5.paragraph.Paragraph,
        CKEditor5.pasteFromOffice.PasteFromOffice,
        CKEditor5.table.Table,
        CKEditor5.table.TableToolbar
    ],
    toolbar: {
        items: [
            'heading',
            '|',
            'bold',
            'italic',
            'link',
            'bulletedList',
            'numberedList',
            '|',
            'outdent',
            'indent',
            '|',
            'uploadImage',
            'blockQuote',
            'insertTable',
            'mediaEmbed',
            'undo',
            'redo'
        ]
    },
    image: {
        toolbar: [
            'imageStyle:inline',
            'imageStyle:block',
            'imageStyle:side',
            '|',
            'toggleImageCaption',
            'imageTextAlternative'
        ]
    },
    table: {
        contentToolbar: [
            'tableColumn',
            'tableRow',
            'mergeTableCells'
        ]
    }
};

CKEditor5.editorClassic.ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        ...config
    } )
    .then( editor => {
            window.editor = editor;
    } );
</script>

```

After 

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

<script type="importmap">
{
    "imports": {
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"
    }
}
</script>
<script type="module">
import {
    ClassicEditor,
    Autoformat,
    Bold,
    Italic,
    BlockQuote,
    Essentials,
    Heading,
    Image,
    ImageCaption,
    ImageStyle,
    ImageToolbar,
    ImageUpload,
    Indent,
    Link,
    List,
    MediaEmbed,
    Paragraph,
    PasteFromOffice,
    Table,
    TableToolbar
} from 'ckeditor5';

const config = {
    plugins: [
        Autoformat,
        Bold,
        Italic,
        BlockQuote,
        Essentials,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        Table,
        TableToolbar
    ],
    toolbar: {
        items: [
            'heading',
            '|',
            'bold',
            'italic',
            'link',
            'bulletedList',
            'numberedList',
            '|',
            'outdent',
            'indent',
            '|',
            'uploadImage',
            'blockQuote',
            'insertTable',
            'mediaEmbed',
            'undo',
            'redo'
        ]
    },
    image: {
        toolbar: [
            'imageStyle:inline',
            'imageStyle:block',
            'imageStyle:side',
            '|',
            'toggleImageCaption',
            'imageTextAlternative'
        ]
    },
    table: {
        contentToolbar: [
            'tableColumn',
            'tableRow',
            'mergeTableCells'
        ]
    }
};

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        ...config
    } )
    .then( editor => {
            window.editor = editor;
    } );
</script>

```

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html">source file: "ckeditor5/latest/updating/nim-migration/migrating-imports.html"</a>

## Migrating imports (v46+)

As part of the transition to the New Installation Methods (NIM) in version, we have standardized how public API elements are exposed in CKEditor 5 and related packages. We introduced a unified export policy that ensures every public entity is exported via the package’s `index.ts` file. We also gave the exported classes, functions, and helpers more descriptive and context-appropriate names ensuring they are unambiguous and unique within the scope of CKEditor 5\. This includes renaming existing exports where needed. The changes are semantically equivalent but introduce breaking changes in naming.

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--using-internal-apis">

### Using internal APIs

For a long time in Old Installation Methods (OIM), it was possible to grab internal-purpose functions from specific files if they were exported just for the package’s internal purposes.

We want to clean up this situation in the New Installation Methods, and internal APIs will not be available in the index. After deprecating OIM, source files will not be available, so some internal APIs that were previously used in this way will no longer be available.

To ease the migration, all internal exports that were available before, are now available directly from the `ckeditor5` (or `ckeditor5-premium-features`) package root with an underscore (`_`) prefix.

Keep in mind that:

* we may remove them in the future.
* all new internal methods will not be added to the indexes.

If you think one of our internal methods, classes, etc. should be available in the public API, please let us know via [the support channel](https://ckeditor.com/contact/) or on [the GitHub issue tracker](https://github.com/ckeditor/ckeditor5/issues).

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--example-migration">

#### Example migration

Previously, importing internal exports required specifying the exact file path:

```
import { getCsrfToken } from '@ckeditor/ckeditor5-adapter-ckfinder/src/utils';

```

Now, you can import them from the package’s root entry point with the new name:

```
import { _getCKFinderCsrfToken } from 'ckeditor5';

```

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--changed-exports">

### Changed exports

Below, you will find all name changes in packages listed alphabetically for convenience.

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-adapter-ckfinder">

#### @ckeditor/ckeditor5-adapter-ckfinder

| file     | original name | re-exported name       |
| -------- | ------------- | ---------------------- |
| utils.ts | getCsrfToken  | \_getCKFinderCsrfToken |
| utils.ts | getCookie     | \_getCKFinderCookie    |
| utils.ts | setCookie     | \_setCKFinderCookie    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-ai">

#### @ckeditor/ckeditor5-ai

| file                         | original name          | re-exported name       |
| ---------------------------- | ---------------------- | ---------------------- |
| adapters/aitextadapter.ts    | RequestHeaders         | AIRequestHeaders       |
| adapters/aitextadapter.ts    | RequestParameters      | AIRequestParameters    |
| adapters/awstextadapter.ts   | AWSTextAdapterConfig   | AIAWSTextAdapterConfig |
| adapters/awstextadapter.ts   | AWSModelFamily         | AIAWSModelFamily       |
| aiasistant.ts                | getDefaultCommands     | getDefaultAICommands   |
| aiasistant.ts                | GroupDefinition        | AIGroupDefinition      |
| aiasistant.ts                | CommandDefinition      | AICommandDefinition    |
| aiconfig.ts                  | AIConfig               | AIConfig               |
| ui/showaiassistantcommand.ts | ShowAIAssistantCommand | ShowAIAssistantCommand |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-alignment">

#### @ckeditor/ckeditor5-alignment

| file               | original name             | re-exported name                |
| ------------------ | ------------------------- | ------------------------------- |
| alignmentconfig.ts | SupportedOption           | AlignmentSupportedOption        |
| utils.ts           | supportedOptions          | \_ALIGNMENT\_SUPPORTED\_OPTIONS |
| utils.ts           | isSupported               | \_isAlignmentSupported          |
| utils.ts           | isDefault                 | \_isDefaultAlignment            |
| utils.ts           | normalizeAlignmentOptions | \_normalizeAlignmentOptions     |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-autoformat">

#### @ckeditor/ckeditor5-autoformat

| file                       | original name | re-exported name       |
| -------------------------- | ------------- | ---------------------- |
| inlineautoformatediting.ts | TestCallback  | AutoformatTestCallback |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-basic-styles">

#### @ckeditor/ckeditor5-basic-styles

| file     | original name    | re-exported name              |
| -------- | ---------------- | ----------------------------- |
| utils.ts | getButtonCreator | \_getBasicStylesButtonCreator |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-bookmark">

#### @ckeditor/ckeditor5-bookmark

| file     | original name     | re-exported name    |
| -------- | ----------------- | ------------------- |
| utils.ts | isBookmarkIdValid | \_isBookmarkIdValid |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-case-change">

#### @ckeditor/ckeditor5-case-change

| file          | original name               | re-exported name                      |
| ------------- | --------------------------- | ------------------------------------- |
| casechange.ts | ExcludeWordsCallback        | CaseChangeExcludeWordsCallback        |
| casechange.ts | ExcludeWordsCallbackContext | CaseChangeExcludeWordsCallbackContext |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-ckbox">

#### @ckeditor/ckeditor5-ckbox

| file                    | original name                       | re-exported name                      |
| ----------------------- | ----------------------------------- | ------------------------------------- |
| ckboxcommand.ts         | prepareImageAssetAttributes         | \_prepareCKBoxImageAssetAttributes    |
| ckboxconfig.ts          | CKBoxAssetDefinition                | \_CKBoxAssetDefinition                |
| ckboxconfig.ts          | CKBoxAssetImageDefinition           | \_CKBoxAssetImageDefinition           |
| ckboxconfig.ts          | CKBoxAssetLinkDefinition            | \_CKBoxAssetLinkDefinition            |
| ckboxconfig.ts          | CKBoxAssetImageAttributesDefinition | \_CKBoxAssetImageAttributesDefinition |
| ckboxconfig.ts          | CKBoxAssetLinkAttributesDefinition  | \_CKBoxAssetLinkAttributesDefinition  |
| ckboximageedit/utils.ts | createEditabilityChecker            | \_createCKBoxEditabilityChecker       |
| utils.ts                | getImageUrls                        | \_getCKBoxImageUrls                   |
| utils.ts                | getWorkspaceId                      | \_getCKBoxWorkspaceId                 |
| utils.ts                | blurHashToDataUrl                   | \_ckboxBlurHashToDataUrl              |
| utils.ts                | sendHttpRequest                     | \_sendCKBoxHttpRequest                |
| utils.ts                | convertMimeTypeToExtension          | \_ckBoxConvertMimeTypeToExtension     |
| utils.ts                | getContentTypeOfUrl                 | \_getCKBoxContentTypeOfUrl            |
| utils.ts                | getFileExtension                    | \_getCKBoxFileExtension               |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-clipboard">

#### @ckeditor/ckeditor5-clipboard

| file                            | original name                   | re-exported name                  |
| ------------------------------- | ------------------------------- | --------------------------------- |
| clipboardmarkersutils.ts        | ClipboardMarkersUtils           | \_ClipboardMarkersUtils           |
| clipboardmarkersutils.ts        | ClipboardMarkerRestrictedAction | \_ClipboardMarkerRestrictedAction |
| clipboardmarkersutils.ts        | ClipboardMarkerConfiguration    | \_ClipboardMarkerConfiguration    |
| dragdrop.ts                     | DragDrop                        | \_DragDrop                        |
| dragdropblocktoolbar.ts         | DragDropBlockToolbar            | \_DragDropBlockToolbar            |
| dragdroptarget.ts               | DragDropTarget                  | \_DragDropTarget                  |
| lineview.ts                     | LineView                        | \_ClipboardLineView               |
| utils/normalizeclipboarddata.ts | normalizeClipboardData          | \_normalizeClipboardData          |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-cloud-services">

#### @ckeditor/ckeditor5-cloud-services

| file                          | original name                  | re-exported name                            |
| ----------------------------- | ------------------------------ | ------------------------------------------- |
| token/token.ts                | TokenOptions                   | CloudServicesTokenOptions                   |
| uploadgateway/fileuploader.ts | FileUploaderErrorEvent         | CloudServicesFileUploaderErrorEvent         |
| uploadgateway/fileuploader.ts | FileUploaderProgressErrorEvent | CloudServicesFileUploaderProgressErrorEvent |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-code-block">

#### @ckeditor/ckeditor5-code-block

| file          | original name                                | re-exported name                                        |
| ------------- | -------------------------------------------- | ------------------------------------------------------- |
| converters.ts | modelToViewCodeBlockInsertion                | \_modelToViewCodeBlockInsertion                         |
| converters.ts | modelToDataViewSoftBreakInsertion            | \_modelToDataViewCodeBlockSoftBreakInsertion            |
| converters.ts | dataViewToModelCodeBlockInsertion            | \_dataViewToModelCodeBlockInsertion                     |
| converters.ts | dataViewToModelTextNewlinesInsertion         | \_dataViewToModelCodeBlockTextNewlinesInsertion         |
| converters.ts | dataViewToModelOrphanNodeConsumer            | \_dataViewToModelCodeBlockOrphanNodeConsumer            |
| utils.ts      | getNormalizedAndLocalizedLanguageDefinitions | \_getNormalizedAndLocalizedCodeBlockLanguageDefinitions |
| utils.ts      | getPropertyAssociation                       | \_getCodeBlockPropertyAssociation                       |
| utils.ts      | getLeadingWhiteSpaces                        | \_getCodeBlockLeadingWhiteSpaces                        |
| utils.ts      | rawSnippetTextToViewDocumentFragment         | \_rawCodeBlockSnippetTextToViewDocumentFragment         |
| utils.ts      | getIndentOutdentPositions                    | \_getCodeBlockIndentOutdentPositions                    |
| utils.ts      | isModelSelectionInCodeBlock                  | \_isModelSelectionInCodeBlock                           |
| utils.ts      | canBeCodeBlock                               | \_canBeCodeBlock                                        |
| utils.ts      | getCodeBlockAriaAnnouncement                 | \_getCodeBlockAriaAnnouncement                          |
| utils.ts      | getTextNodeAtLineStart                       | \_getCodeBlockTextNodeAtLineStart                       |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-collaboration-core">

#### @ckeditor/ckeditor5-collaboration-core

| file      | original name | re-exported name         |
| --------- | ------------- | ------------------------ |
| config.ts | UsersConfig   | CollaborationUsersConfig |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-comments">

#### @ckeditor/ckeditor5-comments

| file                     | original name               | re-exported name            |
| ------------------------ | --------------------------- | --------------------------- |
| sidebaritemview.ts       | SidebarItemView             | AnnotationsSidebarItemView  |
| sidebarview.ts           | SidebarView                 | AnnotationsSidebarView      |
| basecommentthreadview.ts | UISubmitCommentThreadEvent  | UISubmitCommentThreadEvent  |
| basecommentthreadview.ts | UIRemoveCommentThreadEvent  | UIRemoveCommentThreadEvent  |
| basecommentthreadview.ts | UIResolveCommentThreadEvent | UIResolveCommentThreadEvent |
| basecommentview.ts       | UIAddCommentEvent           | UIAddCommentEvent           |
| basecommentview.ts       | UIUpdateCommentEvent        | UIUpdateCommentEvent        |
| basecommentview.ts       | UIRemoveCommentEvent        | UIRemoveCommentEvent        |
| config.ts                | SidebarConfig               | AnnotationsSidebarConfig    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-core">

#### @ckeditor/ckeditor5-core

| file               | original name         | re-exported name                    |
| ------------------ | --------------------- | ----------------------------------- |
| accessibility.ts   | DEFAULT\_GROUP\_ID    | \_DEFAULT\_ACCESSIBILITY\_GROUP\_ID |
| accessibility.ts   | KeystrokeInfos        | KeystrokeInfoDefinitions            |
| accessibility.ts   | KeystrokeInfoCategory | KeystrokeInfoCategoryDefinition     |
| accessibility.ts   | KeystrokeInfoGroup    | KeystrokeInfoGroupDefinition        |
| editorusagedata.ts | getEditorUsageData    | \_getEditorUsageData                |
| editorusagedata.ts | EditorUsageData       | \_EditorUsageData                   |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-emoji">

#### @ckeditor/ckeditor5-emoji

| file                | original name    | re-exported name   |
| ------------------- | ---------------- | ------------------ |
| emojiconfig.ts      | SkinToneId       | EmojiSkinToneId    |
| emojirepository.ts  | SkinTone         | EmojiSkinTone      |
| isemojisupported.ts | isEmojiSupported | \_isEmojiSupported |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-engine">

#### @ckeditor/ckeditor5-engine

| file                                 | original name                            | re-exported name                                           |
| ------------------------------------ | ---------------------------------------- | ---------------------------------------------------------- |
| conversion/downcastdispatcher.ts     | DiffItemReinsert                         | DifferItemReinsert                                         |
| conversion/downcasthelpers.ts        | insertText                               | \_downcastInsertText                                       |
| conversion/downcasthelpers.ts        | insertAttributesAndChildren              | \_downcastInsertAttributesAndChildren                      |
| conversion/downcasthelpers.ts        | remove                                   | \_downcastRemove                                           |
| conversion/downcasthelpers.ts        | createViewElementFromHighlightDescriptor | \_downcastCreateViewElementFromDowncastHighlightDescriptor |
| conversion/downcasthelpers.ts        | convertRangeSelection                    | \_downcastConvertRangeSelection                            |
| conversion/downcasthelpers.ts        | convertCollapsedSelection                | \_downcastConvertCollapsedSelection                        |
| conversion/downcasthelpers.ts        | cleanSelection                           | \_downcastCleanSelection                                   |
| conversion/downcasthelpers.ts        | wrap                                     | \_downcastWrap                                             |
| conversion/downcasthelpers.ts        | insertElement                            | \_downcastInsertElement                                    |
| conversion/downcasthelpers.ts        | insertStructure                          | \_downcastInsertStructure                                  |
| conversion/downcasthelpers.ts        | insertUIElement                          | \_downcastInsertUIElement                                  |
| conversion/downcasthelpers.ts        | HighlightDescriptor                      | DowncastHighlightDescriptor                                |
| conversion/downcasthelpers.ts        | SlotFilter                               | DowncastSlotFilter                                         |
| conversion/downcasthelpers.ts        | ElementCreatorFunction                   | DowncastElementCreatorFunction                             |
| conversion/downcasthelpers.ts        | StructureCreatorFunction                 | DowncastStructureCreatorFunction                           |
| conversion/downcasthelpers.ts        | AttributeElementCreatorFunction          | DowncastAttributeElementCreatorFunction                    |
| conversion/downcasthelpers.ts        | AttributeCreatorFunction                 | DowncastAttributeCreatorFunction                           |
| conversion/downcasthelpers.ts        | AttributeDescriptor                      | DowncastAttributeDescriptor                                |
| conversion/downcasthelpers.ts        | MarkerElementCreatorFunction             | DowncastMarkerElementCreatorFunction                       |
| conversion/downcasthelpers.ts        | HighlightDescriptorCreatorFunction       | DowncastHighlightDescriptorCreatorFunction                 |
| conversion/downcasthelpers.ts        | AddHighlightCallback                     | DowncastAddHighlightCallback                               |
| conversion/downcasthelpers.ts        | RemoveHighlightCallback                  | DowncastRemoveHighlightCallback                            |
| conversion/downcasthelpers.ts        | MarkerDataCreatorFunction                | DowncastMarkerDataCreatorFunction                          |
| conversion/downcasthelpers.ts        | ConsumerFunction                         | \_DowncastConsumerFunction                                 |
| conversion/mapper.ts                 | MapperCache                              | \_MapperCache                                              |
| conversion/upcasthelpers.ts          | convertToModelFragment                   | \_upcastConvertToModelFragment                             |
| conversion/upcasthelpers.ts          | convertText                              | \_upcastConvertText                                        |
| conversion/upcasthelpers.ts          | convertSelectionChange                   | \_upcastConvertSelectionChange                             |
| conversion/upcasthelpers.ts          | ElementCreatorFunction                   | UpcastElementCreatorFunction                               |
| conversion/upcasthelpers.ts          | AttributeCreatorFunction                 | UpcastAttributeCreatorFunction                             |
| conversion/upcasthelpers.ts          | MarkerFromElementCreatorFunction         | UpcastMarkerFromElementCreatorFunction                     |
| conversion/upcasthelpers.ts          | MarkerFromAttributeCreatorFunction       | UpcastMarkerFromAttributeCreatorFunction                   |
| conversion/viewconsumable.ts         | ViewElementConsumables                   | \_ViewElementConversionConsumables                         |
| conversion/viewconsumable.ts         | normalizeConsumables                     | \_normalizeConversionConsumables                           |
| dataprocessor/basichtmlwriter.ts     | BasicHtmlWriter                          | \_DataProcessorBasicHtmlWriter                             |
| dataprocessor/htmlwriter.ts          | HtmlWriter                               | DataProcessorHtmlWriter                                    |
| dev-utils/model.ts                   | getData                                  | \_getModelData                                             |
| dev-utils/model.ts                   | setData                                  | \_setModelData                                             |
| dev-utils/model.ts                   | stringify                                | \_stringifyModel                                           |
| dev-utils/model.ts                   | parse                                    | \_parseModel                                               |
| dev-utils/operationreplayer.ts       | OperationReplayer                        | \_OperationReplayer                                        |
| dev-utils/utils.ts                   | convertMapToTags                         | \_convertMapToTags                                         |
| dev-utils/utils.ts                   | convertMapToStringifiedObject            | \_convertMapToStringifiedObject                            |
| dev-utils/utils.ts                   | dumpTrees                                | \_dumpTrees                                                |
| dev-utils/utils.ts                   | initDocumentDumping                      | \_initDocumentDumping                                      |
| dev-utils/utils.ts                   | logDocument                              | \_logDocument                                              |
| dev-utils/view.ts                    | getData                                  | \_getViewData                                              |
| dev-utils/view.ts                    | setData                                  | \_setViewData                                              |
| dev-utils/view.ts                    | stringify                                | \_stringifyView                                            |
| dev-utils/view.ts                    | parse                                    | \_parseView                                                |
| model/differ.ts                      | DifferSnapshot                           | \_DifferSnapshot                                           |
| model/differ.ts                      | DiffItem                                 | DifferItem                                                 |
| model/differ.ts                      | DiffItemInsert                           | DifferItemInsert                                           |
| model/differ.ts                      | DiffItemRemove                           | DifferItemRemove                                           |
| model/differ.ts                      | DiffItemAttribute                        | DifferItemAttribute                                        |
| model/differ.ts                      | DiffItemRoot                             | DifferItemRoot                                             |
| model/document.ts                    | Document                                 | ModelDocument                                              |
| model/document.ts                    | DocumentChangeEvent                      | ModelDocumentChangeEvent                                   |
| model/documentfragment.ts            | DocumentFragment                         | ModelDocumentFragment                                      |
| model/documentselection.ts           | DocumentSelection                        | ModelDocumentSelection                                     |
| model/documentselection.ts           | DocumentSelectionChangeRangeEvent        | ModelDocumentSelectionChangeRangeEvent                     |
| model/documentselection.ts           | DocumentSelectionChangeAttributeEvent    | ModelDocumentSelectionChangeAttributeEvent                 |
| model/documentselection.ts           | DocumentSelectionChangeMarkerEvent       | ModelDocumentSelectionChangeMarkerEvent                    |
| model/documentselection.ts           | DocumentSelectionChangeEvent             | ModelDocumentSelectionChangeEvent                          |
| model/element.ts                     | Element                                  | ModelElement                                               |
| model/item.ts                        | Item                                     | ModelItem                                                  |
| model/liveposition.ts                | LivePosition                             | ModelLivePosition                                          |
| model/liveposition.ts                | LivePositionChangeEvent                  | ModelLivePositionChangeEvent                               |
| model/liverange.ts                   | LiveRange                                | ModelLiveRange                                             |
| model/liverange.ts                   | LiveRangeChangeRangeEvent                | ModelLiveRangeChangeRangeEvent                             |
| model/liverange.ts                   | LiveRangeChangeContentEvent              | ModelLiveRangeChangeContentEvent                           |
| model/liverange.ts                   | LiveRangeChangeEvent                     | ModelLiveRangeChangeEvent                                  |
| model/model.ts                       | BeforeChangesEvent                       | \_ModelBeforeChangesEvent                                  |
| model/model.ts                       | AfterChangesEvent                        | \_ModelAfterChangesEvent                                   |
| model/node.ts                        | Node                                     | ModelNode                                                  |
| model/node.ts                        | NodeAttributes                           | ModelNodeAttributes                                        |
| model/nodelist.ts                    | NodeList                                 | ModelNodeList                                              |
| model/operation/detachoperation.ts   | DetachOperation                          | \_DetachOperation                                          |
| model/operation/transform.ts         | transform                                | \_operationTransform                                       |
| model/operation/transform.ts         | transformSets                            | transformOperationSets                                     |
| model/operation/transform.ts         | TransformSetsResult                      | TransformOperationSetsResult                               |
| model/operation/transform.ts         | TransformationContext                    | \_OperationTransformationContext                           |
| model/operation/utils.ts             | \_insert                                 | \_insertIntoModelNodeList                                  |
| model/operation/utils.ts             | \_remove                                 | \_removeFromModelNodeList                                  |
| model/operation/utils.ts             | \_move                                   | \_moveInModelNodeList                                      |
| model/operation/utils.ts             | \_setAttribute                           | \_setAttributeInModelNodeList                              |
| model/operation/utils.ts             | \_normalizeNodes                         | \_normalizeInModelNodeList                                 |
| model/operation/utils.ts             | NodeSet                                  | ModelNodeSet                                               |
| model/position.ts                    | Position                                 | ModelPosition                                              |
| model/position.ts                    | PositionRelation                         | ModelPositionRelation                                      |
| model/position.ts                    | PositionOffset                           | ModelPositionOffset                                        |
| model/position.ts                    | PositionStickiness                       | ModelPositionStickiness                                    |
| model/position.ts                    | getTextNodeAtPosition                    | \_getModelTextNodeAtPosition                               |
| model/position.ts                    | getNodeAfterPosition                     | \_getModelNodeAfterPosition                                |
| model/position.ts                    | getNodeBeforePosition                    | \_getModelNodeBeforePosition                               |
| model/range.ts                       | Range                                    | ModelRange                                                 |
| model/rootelement.ts                 | RootElement                              | ModelRootElement                                           |
| model/schema.ts                      | Schema                                   | ModelSchema                                                |
| model/schema.ts                      | SchemaCheckChildEvent                    | ModelSchemaCheckChildEvent                                 |
| model/schema.ts                      | SchemaCheckAttributeEvent                | ModelSchemaCheckAttributeEvent                             |
| model/schema.ts                      | SchemaItemDefinition                     | ModelSchemaItemDefinition                                  |
| model/schema.ts                      | SchemaCompiledItemDefinition             | ModelSchemaCompiledItemDefinition                          |
| model/schema.ts                      | SchemaContext                            | ModelSchemaContext                                         |
| model/schema.ts                      | SchemaContextDefinition                  | ModelSchemaContextDefinition                               |
| model/schema.ts                      | SchemaContextItem                        | ModelSchemaContextItem                                     |
| model/schema.ts                      | AttributeProperties                      | ModelAttributeProperties                                   |
| model/schema.ts                      | SchemaAttributeCheckCallback             | ModelSchemaAttributeCheckCallback                          |
| model/schema.ts                      | SchemaChildCheckCallback                 | ModelSchemaChildCheckCallback                              |
| model/selection.ts                   | Selection                                | ModelSelection                                             |
| model/selection.ts                   | SelectionChangeEvent                     | ModelSelectionChangeEvent                                  |
| model/selection.ts                   | SelectionChangeRangeEvent                | ModelSelectionChangeRangeEvent                             |
| model/selection.ts                   | SelectionChangeAttributeEvent            | ModelSelectionChangeAttributeEvent                         |
| model/selection.ts                   | Selectable                               | ModelSelectable                                            |
| model/selection.ts                   | PlaceOrOffset                            | ModelPlaceOrOffset                                         |
| model/text.ts                        | Text                                     | ModelText                                                  |
| model/textproxy.ts                   | TextProxy                                | ModelTextProxy                                             |
| model/treewalker.ts                  | TreeWalker                               | ModelTreeWalker                                            |
| model/treewalker.ts                  | TreeWalkerValueType                      | ModelTreeWalkerValueType                                   |
| model/treewalker.ts                  | TreeWalkerValue                          | ModelTreeWalkerValue                                       |
| model/treewalker.ts                  | TreeWalkerDirection                      | ModelTreeWalkerDirection                                   |
| model/treewalker.ts                  | TreeWalkerOptions                        | ModelTreeWalkerOptions                                     |
| model/typecheckable.ts               | TypeCheckable                            | ModelTypeCheckable                                         |
| model/utils/autoparagraphing.ts      | autoParagraphEmptyRoots                  | \_autoParagraphEmptyModelRoots                             |
| model/utils/autoparagraphing.ts      | isParagraphable                          | \_isParagraphableModelNode                                 |
| model/utils/autoparagraphing.ts      | wrapInParagraph                          | \_wrapInParagraphModelNode                                 |
| model/utils/deletecontent.ts         | deleteContent                            | \_deleteModelContent                                       |
| model/utils/getselectedcontent.ts    | getSelectedContent                       | \_getSelectedModelContent                                  |
| model/utils/insertcontent.ts         | insertContent                            | \_insertModelContent                                       |
| model/utils/insertobject.ts          | insertObject                             | \_insertModelObject                                        |
| model/utils/modifyselection.ts       | modifySelection                          | \_modifyModelSelection                                     |
| model/utils/selection-post-fixer.ts  | injectSelectionPostFixer                 | \_injectModelSelectionPostFixer                            |
| model/utils/selection-post-fixer.ts  | tryFixingRange                           | \_tryFixingModelRange                                      |
| model/utils/selection-post-fixer.ts  | mergeIntersectingRanges                  | \_mergeIntersectingModelRanges                             |
| model/writer.ts                      | Writer                                   | ModelWriter                                                |
| view/attributeelement.ts             | AttributeElement                         | ViewAttributeElement                                       |
| view/containerelement.ts             | ContainerElement                         | ViewContainerElement                                       |
| view/containerelement.ts             | getFillerOffset                          | getViewFillerOffset                                        |
| view/datatransfer.ts                 | DataTransfer                             | ViewDataTransfer                                           |
| view/datatransfer.ts                 | EffectAllowed                            | ViewEffectAllowed                                          |
| view/datatransfer.ts                 | DropEffect                               | ViewDropEffect                                             |
| view/document.ts                     | Document                                 | ViewDocument                                               |
| view/document.ts                     | ViewDocumentPostFixer                    | ViewDocumentPostFixer                                      |
| view/document.ts                     | ChangeType                               | ViewDocumentChangeType                                     |
| view/documentfragment.ts             | DocumentFragment                         | ViewDocumentFragment                                       |
| view/documentselection.ts            | DocumentSelection                        | ViewDocumentSelection                                      |
| view/domconverter.ts                 | DomConverter                             | ViewDomConverter                                           |
| view/downcastwriter.ts               | DowncastWriter                           | ViewDowncastWriter                                         |
| view/editableelement.ts              | EditableElement                          | ViewEditableElement                                        |
| view/element.ts                      | Element                                  | ViewElement                                                |
| view/element.ts                      | ElementAttributeValue                    | ViewElementAttributeValue                                  |
| view/element.ts                      | ElementAttributes                        | ViewElementAttributes                                      |
| view/element.ts                      | NormalizedConsumables                    | ViewNormalizedConsumables                                  |
| view/elementdefinition.ts            | ElementObjectDefinition                  | ViewElementObjectDefinition                                |
| view/elementdefinition.ts            | ElementDefinition                        | ViewElementDefinition                                      |
| view/emptyelement.ts                 | EmptyElement                             | ViewEmptyElement                                           |
| view/filler.ts                       | NBSP\_FILLER                             | \_VIEW\_NBSP\_FILLER                                       |
| view/filler.ts                       | MARKED\_NBSP\_FILLER                     | \_VIEW\_MARKED\_NBSP\_FILLER                               |
| view/filler.ts                       | BR\_FILLER                               | \_VIEW\_BR\_FILLER                                         |
| view/filler.ts                       | INLINE\_FILLER\_LENGTH                   | \_VIEW\_INLINE\_FILLER\_LENGTH                             |
| view/filler.ts                       | INLINE\_FILLER                           | \_VIEW\_INLINE\_FILLER                                     |
| view/filler.ts                       | startsWithFiller                         | \_startsWithViewFiller                                     |
| view/filler.ts                       | isInlineFiller                           | \_isInlineViewFiller                                       |
| view/filler.ts                       | getDataWithoutFiller                     | \_getDataWithoutViewFiller                                 |
| view/filler.ts                       | injectQuirksHandling                     | \_injectViewQuirksHandling                                 |
| view/item.ts                         | Item                                     | ViewItem                                                   |
| view/matcher.ts                      | isPatternMatched                         | \_isViewPatternMatched                                     |
| view/matcher.ts                      | PropertyPatterns                         | MatchPropertyPatterns                                      |
| view/matcher.ts                      | AttributePatterns                        | MatchAttributePatterns                                     |
| view/matcher.ts                      | StylePatterns                            | MatchStylePatterns                                         |
| view/matcher.ts                      | ClassPatterns                            | MatchClassPatterns                                         |
| view/matcher.ts                      | NormalizedPropertyPattern                | \_ViewNormalizedPropertyPattern                            |
| view/node.ts                         | Node                                     | ViewNode                                                   |
| view/observer/arrowkeysobserver.ts   | ArrowKeysObserver                        | ViewDocumentArrowKeyEvent                                  |
| view/observer/bubblingeventinfo.ts   | EventPhase                               | BubblingEventPhase                                         |
| view/observer/compositionobserver.ts | CompositionEventData                     | ViewDocumentCompositionEventData                           |
| view/observer/domeventdata.ts        | DomEventData                             | ViewDocumentDomEventData                                   |
| view/observer/inputobserver.ts       | InputEventData                           | ViewDocumentInputEventData                                 |
| view/observer/keyobserver.ts         | KeyEventData                             | ViewDocumentKeyEventData                                   |
| view/observer/mutationobserver.ts    | MutationsEventData                       | ViewDocumentMutationEventData                              |
| view/observer/mutationobserver.ts    | MutationData                             | ObserverMutationData                                       |
| view/placeholder.ts                  | enablePlaceholder                        | enableViewPlaceholder                                      |
| view/placeholder.ts                  | disablePlaceholder                       | disableViewPlaceholder                                     |
| view/placeholder.ts                  | showPlaceholder                          | showViewPlaceholder                                        |
| view/placeholder.ts                  | hidePlaceholder                          | hideViewPlaceholder                                        |
| view/placeholder.ts                  | needsPlaceholder                         | needsViewPlacegolder                                       |
| view/placeholder.ts                  | PlaceholderableElement                   | PlaceholderableViewElement                                 |
| view/position.ts                     | Position                                 | ViewPosition                                               |
| view/position.ts                     | PositionRelation                         | ViewPositionRelation                                       |
| view/position.ts                     | PositionOffset                           | ViewPositionOffset                                         |
| view/range.ts                        | Range                                    | ViewRange                                                  |
| view/rawelement.ts                   | RawElement                               | ViewRawElement                                             |
| view/renderer.ts                     | Renderer                                 | ViewRenderer                                               |
| view/rooteditableelement.ts          | RootEditableElement                      | ViewRootEditableElement                                    |
| view/selection.ts                    | Selection                                | ViewSelection                                              |
| view/selection.ts                    | SelectionOptions                         | ViewSelectionOptions                                       |
| view/selection.ts                    | PlaceOrOffset                            | ViewPlaceOrOffset                                          |
| view/selection.ts                    | Selectable                               | ViewSelectable                                             |
| view/styles/background.ts            | addBackgroundRules                       | addBackgroundStylesRules                                   |
| view/styles/border.ts                | addBorderRules                           | addBorderStylesRules                                       |
| view/styles/margin.ts                | addMarginRules                           | addMarginStylesRules                                       |
| view/styles/padding.ts               | addPaddingRules                          | addPaddingStylesRules                                      |
| view/styles/utils.ts                 | isColor                                  | isColorStyleValue                                          |
| view/styles/utils.ts                 | isLineStyle                              | isLineStyleValue                                           |
| view/styles/utils.ts                 | isLength                                 | isLengthStyleValue                                         |
| view/styles/utils.ts                 | isPercentage                             | isPercentageStyleValue                                     |
| view/styles/utils.ts                 | isRepeat                                 | isRepeatStyleValue                                         |
| view/styles/utils.ts                 | isPosition                               | isPositionStyleValue                                       |
| view/styles/utils.ts                 | isAttachment                             | isAttachmentStyleValue                                     |
| view/styles/utils.ts                 | isURL                                    | isURLStyleValue                                            |
| view/styles/utils.ts                 | getBoxSidesValues                        | getBoxSidesStyleValues                                     |
| view/styles/utils.ts                 | getBoxSidesValueReducer                  | getBoxSidesStyleValueReducer                               |
| view/styles/utils.ts                 | getBoxSidesShorthandValue                | getBoxSidesStyleShorthandValue                             |
| view/styles/utils.ts                 | getPositionShorthandNormalizer           | getPositionStyleShorthandNormalizer                        |
| view/styles/utils.ts                 | getShorthandValues                       | getShorthandStylesValues                                   |
| view/stylesmap.ts                    | PropertyDescriptor                       | StylePropertyDescriptor                                    |
| view/stylesmap.ts                    | BoxSides                                 | BoxStyleSides                                              |
| view/stylesmap.ts                    | Normalizer                               | StylesNormalizer                                           |
| view/stylesmap.ts                    | Extractor                                | StylesExtractor                                            |
| view/stylesmap.ts                    | Reducer                                  | StylesReducer                                              |
| view/text.ts                         | Text                                     | ViewText                                                   |
| view/textproxy.ts                    | TextProxy                                | ViewTextProxy                                              |
| view/tokenlist.ts                    | TokenList                                | ViewTokenList                                              |
| view/treewalker.ts                   | TreeWalker                               | ViewTreeWalker                                             |
| view/treewalker.ts                   | TreeWalkerValueType                      | ViewTreeWalkerValueType                                    |
| view/treewalker.ts                   | TreeWalkerValue                          | ViewTreeWalkerValue                                        |
| view/treewalker.ts                   | TreeWalkerDirection                      | ViewTreeWalkerDirection                                    |
| view/treewalker.ts                   | TreeWalkerOptions                        | ViewTreeWalkerOptions                                      |
| view/typecheckable.ts                | TypeCheckable                            | ViewTypeCheckable                                          |
| view/uielement.ts                    | UIElement                                | ViewUIElement                                              |
| view/uielement.ts                    | injectUiElementHandling                  | \_injectViewUIElementHandling                              |
| view/upcastwriter.ts                 | UpcastWriter                             | ViewUpcastWriter                                           |
| view/view.ts                         | View                                     | EditingView                                                |
| view/view.ts                         | AlwaysRegisteredObservers                | AlwaysRegisteredViewObservers                              |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-enter">

#### @ckeditor/ckeditor5-enter

| file             | original name            | re-exported name           |
| ---------------- | ------------------------ | -------------------------- |
| enterobserver.ts | EnterObserver            | EnterObserver              |
| enterobserver.ts | EnterEventData           | ViewDocumentEnterEventData |
| utils.ts         | getCopyOnEnterAttributes | \_getCopyOnEnterAttributes |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-export-word">

#### @ckeditor/ckeditor5-export-word

| file          | original name                                     | re-exported name                                    |
| ------------- | ------------------------------------------------- | --------------------------------------------------- |
| exportword.ts | ExportWordConverterInternalOptions                | \_ExportWordConverterInternalOptions                |
| exportword.ts | ExportWordConverterInternalOptionsV2              | \_ExportWordConverterInternalOptionsV2              |
| exportword.ts | ExportWordConverterCollaborationFeaturesOptionsV2 | \_ExportWordConverterCollaborationFeaturesOptionsV2 |
| exportword.ts | ExportWordConverterCommentsThreadOptionsV2        | \_ExportWordConverterCommentsThreadOptionsV2        |
| exportword.ts | ExportWordConverterCommentsV2                     | \_ExportWordConverterCommentsV2                     |
| exportword.ts | ExportWordConverterSuggestionsOptionsV2           | \_ExportWordConverterSuggestionsOptionsV2           |
| exportword.ts | ExportWordConverterMergeFieldsOptionsV2           | \_ExportWordConverterMergeFieldsOptionsV2           |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-find-and-replace">

#### @ckeditor/ckeditor5-find-and-replace

| File                   | original name                      | re-exported name                   |
| ---------------------- | ---------------------------------- | ---------------------------------- |
| findandreplace.ts      | ResultType                         | FindResultType                     |
| findandreplacestate.ts | sortSearchResultsByMarkerPositions | \_sortFindResultsByMarkerPositions |
| findandreplaceui.ts    | SearchResetedEvent                 | FindResetedEvent                   |
| replacecommandbase.ts  | ReplaceCommandBase                 | FindReplaceCommandBase             |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-font">

#### @ckeditor/ckeditor5-font

| File                | original name              | re-exported name                 |
| ------------------- | -------------------------- | -------------------------------- |
| fontfamily/utils.ts | normalizeOptions           | \_normalizeFontFamilyOptions     |
| fontsize/utils.ts   | normalizeOptions           | \_normalizeFontSizeOptions       |
| ui/colorui.ts       | ColorUI                    | FontColorUIBase                  |
| utils.ts            | buildDefinition            | \_buildFontDefinition            |
| utils.ts            | renderUpcastAttribute      | \_renderUpcastFontColorAttribute |
| utils.ts            | renderDowncastElement      | \_renderDowncastFontElement      |
| utils.ts            | addColorSelectorToDropdown | \_addFontColorSelectorToDropdown |
| utils.ts            | ColorSelectorDropdownView  | FontColorSelectorDropdownView    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-fullscreen">

#### @ckeditor/ckeditor5-fullscreen

| File                               | original name          | re-exported name                 |
| ---------------------------------- | ---------------------- | -------------------------------- |
| handlers/abstracteditorhandler.ts  | AbstractEditorHandler  | FullscreenAbstractEditorHandler  |
| handlers/classiceditorhandler.ts   | ClassicEditorHandler   | FullscreenClassicEditorHandler   |
| handlers/decouplededitorhandler.ts | DecoupledEditorHandler | FullscreenDecoupledEditorHandler |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-heading">

#### @ckeditor/ckeditor5-heading

| File     | original name       | re-exported name             |
| -------- | ------------------- | ---------------------------- |
| title.ts | TitleConfig         | HeadingTitleConfig           |
| utils.ts | getLocalizedOptions | \_getLocalizedHeadingOptions |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-html-embed">

#### @ckeditor/ckeditor5-html-embed

| File                | original name | re-exported name  |
| ------------------- | ------------- | ----------------- |
| htmlembedediting.ts | RawHtmlApi    | \_RawHtmlEmbedApi |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-html-support">

#### @ckeditor/ckeditor5-html-support

| file                             | original name                          | re-exported name                                    |
| -------------------------------- | -------------------------------------- | --------------------------------------------------- |
| converters.ts                    | viewToModelObjectConverter             | \_viewToModelObjectContentHtmlSupportConverter      |
| converters.ts                    | toObjectWidgetConverter                | \_toObjectWidgetHtmlSupportConverter                |
| converters.ts                    | createObjectView                       | \_createObjectHtmlSupportView                       |
| converters.ts                    | viewToAttributeInlineConverter         | \_viewToAttributeInlineHtmlSupportConverter         |
| converters.ts                    | emptyInlineModelElementToViewConverter | \_emptyInlineModelElementToViewHtmlSupportConverter |
| converters.ts                    | attributeToViewInlineConverter         | \_attributeToInlineHtmlSupportConverter             |
| converters.ts                    | viewToModelBlockAttributeConverter     | \_viewToModelBlockAttributeHtmlSupportConverter     |
| converters.ts                    | modelToViewBlockAttributeConverter     | \_modelToViewBlockAttributeHtmlSupportConverter     |
| datafilter.ts                    | DataFilterRegisterEvent                | HtmlSupportDataFilterRegisterEvent                  |
| dataschema.ts                    | DataSchemaDefinition                   | HtmlSupportDataSchemaDefinition                     |
| dataschema.ts                    | DataSchemaBlockElementDefinition       | HtmlSupportDataSchemaBlockElementDefinition         |
| dataschema.ts                    | DataSchemaInlineElementDefinition      | HtmlSupportDataSchemaInlineElementDefinition        |
| generalhtmlsupportconfig.ts      | FullPageConfig                         | GHSFullPageConfig                                   |
| generalhtmlsupportconfig.ts      | CssSanitizeOutput                      | GHSCssSanitizeOutput                                |
| integrations/integrationutils.ts | getDescendantElement                   | \_getHtmlSupportDescendantElement                   |
| schemadefinitions.ts             | \_HTML\_SUPPORT\_SCHEMA\_DEFINITIONS   |                                                     |
| utils.ts                         | updateViewAttributes                   | \_updateHtmlSupportViewAttributes                   |
| utils.ts                         | setViewAttributes                      | \_setHtmlSupportViewAttributes                      |
| utils.ts                         | removeViewAttributes                   | \_removeHtmlSupportViewAttributes                   |
| utils.ts                         | mergeViewElementAttributes             | \_mergeHtmlSupportViewElementAttributes             |
| utils.ts                         | modifyGhsAttribute                     | \_modifyHtmlSupportGhsAttribute                     |
| utils.ts                         | toPascalCase                           | \_toHtmlSupportPascalCase                           |
| utils.ts                         | getHtmlAttributeName                   | \_getHtmlSupportAttributeName                       |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-image">

#### @ckeditor/ckeditor5-image

| file                                                     | original name                             | re-exported name                             |
| -------------------------------------------------------- | ----------------------------------------- | -------------------------------------------- |
| image/converters.ts                                      | upcastImageFigure                         | \_upcastImageFigure                          |
| image/converters.ts                                      | upcastPicture                             | \_upcastImagePicture                         |
| image/converters.ts                                      | downcastSrcsetAttribute                   | \_downcastImageSrcsetAttribute               |
| image/converters.ts                                      | downcastSourcesAttribute                  | \_downcastImageSourcesAttribute              |
| image/converters.ts                                      | downcastImageAttribute                    | \_downcastImageAttribute                     |
| image/imageloadobserver.ts                               | ImageLoadObserver                         | ImageLoadObserver                            |
| image/ui/utils.ts                                        | repositionContextualBalloon               | \_repositionImageContextualBalloon           |
| image/ui/utils.ts                                        | getBalloonPositionData                    | \_getImageBalloonPositionData                |
| image/utils.ts                                           | createInlineImageViewElement              | \_createInlineImageViewElement               |
| image/utils.ts                                           | createBlockImageViewElement               | \_createBlockImageViewElement                |
| image/utils.ts                                           | getImgViewElementMatcher                  | \_getImageViewElementMatcher                 |
| image/utils.ts                                           | determineImageTypeForInsertionAtSelection | \_determineImageTypeForInsertionAtSelection  |
| image/utils.ts                                           | getSizeValueIfInPx                        | \_getImageSizeValueIfInPx                    |
| image/utils.ts                                           | widthAndHeightStylesAreBothSet            | \_checkIfImageWidthAndHeightStylesAreBothSet |
| imageinsert/ui/imageinsertformview.ts                    | ImageInsertFormView                       | \_ImageInsertFormView                        |
| imageinsert/ui/imageinserturlview.ts                     | ImageInsertUrlView                        | \_ImageInsertUrlView                         |
| imageresize/ui/imagecustomresizeformview.ts              | ImageCustomResizeFormView                 | \_ImageCustomResizeFormView                  |
| imageresize/ui/imagecustomresizeformview.ts              | ImageCustomResizeFormValidatorCallback    | \_ImageCustomResizeFormValidatorCallback     |
| imageresize/utils/getselectedimageeditornodes.ts         | getSelectedImageEditorNodes               | \_getSelectedImageEditorNodes                |
| imageresize/utils/getselectedimagepossibleresizerange.ts | getSelectedImagePossibleResizeRange       | \_getSelectedImagePossibleResizeRange        |
| imageresize/utils/getselectedimagepossibleresizerange.ts | PossibleResizeImageRange                  | \_PossibleResizeImageRange                   |
| imageresize/utils/getselectedimagewidthinunits.ts        | getSelectedImageWidthInUnits              | \_getSelectedImageWidthInUnits               |
| imageresize/utils/tryparsedimensionwithunit.ts           | tryParseDimensionWithUnit                 | \_tryParseImageDimensionWithUnit             |
| imageresize/utils/tryparsedimensionwithunit.ts           | tryCastDimensionsToUnit                   | \_tryCastImageDimensionsToUnit               |
| imageresize/utils/tryparsedimensionwithunit.ts           | DimensionWithUnit                         | \_ImageDimensionWithUnit                     |
| imagestyle/converters.ts                                 | modelToViewStyleAttribute                 | \_modelToViewImageStyleAttribute             |
| imagestyle/converters.ts                                 | viewToModelStyleAttribute                 | \_viewToModelImageStyleAttribute             |
| imagestyle/utils.ts                                      | DEFAULT\_OPTIONS                          | \_IMAGE\_DEFAULT\_OPTIONS                    |
| imagestyle/utils.ts                                      | DEFAULT\_ICONS                            | \_IMAGE\_DEFAULT\_ICONS                      |
| imagestyle/utils.ts                                      | DEFAULT\_DROPDOWN\_DEFINITIONS            | \_IMAGE\_DEFAULT\_DROPDOWN\_DEFINITIONS      |
| imagestyle/utils.ts                                      | \_ImageStyleUtils                         |                                              |
| imagetextalternative/ui/textalternativeformview.ts       | TextAlternativeFormView                   | \_ImageTextAlternativeFormView               |
| imagetextalternative/ui/textalternativeformview.ts       | TextAlternativeFormViewSubmitEvent        | \_ImageTextAlternativeFormViewSubmitEvent    |
| imagetextalternative/ui/textalternativeformview.ts       | TextAlternativeFormViewCancelEvent        | \_ImageTextAlternativeFormViewCancelEvent    |
| imageupload/imageuploadediting.ts                        | isHtmlIncluded                            | isHtmlInDataTransfer                         |
| imageupload/utils.ts                                     | fetchLocalImage                           | \_fetchLocalImage                            |
| imageupload/utils.ts                                     | isLocalImage                              | \_isLocalImage                               |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-import-word">

#### @ckeditor/ckeditor5-import-word

| file                 | original name     | re-exported name            |
| -------------------- | ----------------- | --------------------------- |
| importword.ts        | FormattingOptions | ImportWordFormattingOptions |
| importwordcommand.ts | DataInsertEvent   | ImportWordDataInsertEvent   |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-indent">

#### @ckeditor/ckeditor5-indent

| file                                        | original name      | re-exported name     |
| ------------------------------------------- | ------------------ | -------------------- |
| indentcommandbehavior/indentusingclasses.ts | IndentUsingClasses | \_IndentUsingClasses |
| indentcommandbehavior/indentusingoffset.ts  | IndentUsingOffset  | \_IndentUsingOffset  |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-language">

#### @ckeditor/ckeditor5-language

| file     | original name              | re-exported name             |
| -------- | -------------------------- | ---------------------------- |
| utils.ts | stringifyLanguageAttribute | \_stringifyLanguageAttribute |
| utils.ts | parseLanguageAttribute     | \_parseLanguageAttribute     |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-link">

#### @ckeditor/ckeditor5-link

| file                        | original name            | re-exported name             |
| --------------------------- | ------------------------ | ---------------------------- |
| ui/linkbuttonview.ts        | LinkButtonView           | \_LinkButtonView             |
| ui/linkformview.ts          | SubmitEvent              | LinkFormSubmitEvent          |
| ui/linkformview.ts          | CancelEvent              | LinkFormCancelEvent          |
| ui/linkpreviewbuttonview.ts | LinkPreviewButtonView    | \_LinkPreviewButtonView      |
| ui/linkpropertiesview.ts    | BackEvent                | LinkPropertiesBackEvent      |
| ui/linkprovideritemsview.ts | CancelEvent              | LinkProvidersCancelEvent     |
| utils.ts                    | LINK\_KEYSTROKE          | \_LINK\_KEYSTROKE            |
| utils.ts                    | createLinkElement        | \_createLinkElement          |
| utils.ts                    | ensureSafeUrl            | \_ensureSafeLinkUrl          |
| utils.ts                    | getLocalizedDecorators   | \_getLocalizedLinkDecorators |
| utils.ts                    | normalizeDecorators      | \_normalizeLinkDecorators    |
| utils.ts                    | isEmail                  | \_isEmailLink                |
| utils.ts                    | linkHasProtocol          | \_hasLinkProtocol            |
| utils.ts                    | openLink                 | \_openLink                   |
| utils.ts                    | extractTextFromLinkRange | \_extractTextFromLinkRange   |
| utils/manualdecorator.ts    | ManualDecorator          | LinkManualDecorator          |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-list">

#### @ckeditor/ckeditor5-list

| file                                    | original name                      | re-exported name                      |
| --------------------------------------- | ---------------------------------- | ------------------------------------- |
| list/converters.ts                      | listItemUpcastConverter            | \_listItemUpcastConverter             |
| list/converters.ts                      | reconvertItemsOnDataChange         | \_reconvertListItemsOnDataChange      |
| list/converters.ts                      | listItemDowncastConverter          | \_listItemDowncastConverter           |
| list/converters.ts                      | listItemDowncastRemoveConverter    | \_listItemDowncastRemoveConverter     |
| list/converters.ts                      | bogusParagraphCreator              | \_listItemBogusParagraphCreator       |
| list/converters.ts                      | findMappedViewElement              | \_findMappedListItemViewElement       |
| list/converters.ts                      | createModelToViewPositionMapper    | \_createModelToViewListPositionMapper |
| list/listcommand.ts                     | ListCommandAfterExecuteEvent       | \_ListCommandAfterExecuteEvent        |
| list/listediting.ts                     | ListItemAttributesMap              | \_ListItemAttributesMap               |
| list/listediting.ts                     | ListEditingCheckAttributesEvent    | \_ListEditingCheckAttributesEvent     |
| list/listediting.ts                     | ListEditingCheckElementEvent       | \_ListEditingCheckElementEvent        |
| list/listindentcommand.ts               | ListIndentCommandAfterExecuteEvent | \_ListIndentCommandAfterExecuteEvent  |
| list/listmergecommand.ts                | ListMergeCommandAfterExecuteEvent  | \_ListMergeCommandAfterExecuteEvent   |
| list/listsplitcommand.ts                | ListSplitCommandAfterExecuteEvent  | \_ListSplitCommandAfterExecuteEvent   |
| list/utils.ts                           | createUIComponents                 | \_createListUIComponents              |
| list/utils/listwalker.ts                | ListWalker                         | \_ListWalker                          |
| list/utils/listwalker.ts                | SiblingListBlocksIterator          | \_SiblingListBlocksIterator           |
| list/utils/listwalker.ts                | ListBlocksIterable                 | \_ListBlocksIterable                  |
| list/utils/listwalker.ts                | ListIteratorValue                  | \_ListIteratorValue                   |
| list/utils/listwalker.ts                | ListWalkerOptions                  | \_ListWalkerOptions                   |
| list/utils/model.ts                     | ListItemUid                        | \_ListItemUid                         |
| list/utils/model.ts                     | ListElement                        | \_ListElement                         |
| list/utils/model.ts                     | isListItemBlock                    | \_isListItemBlock                     |
| list/utils/model.ts                     | getAllListItemBlocks               | \_getAllListItemBlocks                |
| list/utils/model.ts                     | getListItemBlocks                  | \_getListItemBlocks                   |
| list/utils/model.ts                     | getNestedListBlocks                | \_getNestedListBlocks                 |
| list/utils/model.ts                     | getListItems                       | \_getListItems                        |
| list/utils/model.ts                     | isFirstBlockOfListItem             | \_isFirstBlockOfListItem              |
| list/utils/model.ts                     | isLastBlockOfListItem              | \_isLastBlockOfListItem               |
| list/utils/model.ts                     | expandListBlocksToCompleteItems    | \_expandListBlocksToCompleteItems     |
| list/utils/model.ts                     | expandListBlocksToCompleteList     | \_expandListBlocksToCompleteList      |
| list/utils/model.ts                     | splitListItemBefore                | \_splitListItemBefore                 |
| list/utils/model.ts                     | mergeListItemBefore                | \_mergeListItemBefore                 |
| list/utils/model.ts                     | indentBlocks                       | \_indentListBlocks                    |
| list/utils/model.ts                     | outdentBlocksWithMerge             | \_outdentListBlocksWithMerge          |
| list/utils/model.ts                     | removeListAttributes               | \_removeListAttributes                |
| list/utils/model.ts                     | isSingleListItem                   | \_isSingleListItem                    |
| list/utils/model.ts                     | outdentFollowingItems              | \_outdentFollowingListItems           |
| list/utils/model.ts                     | sortBlocks                         | \_sortListBlocks                      |
| list/utils/model.ts                     | getSelectedBlockObject             | \_getSelectedBlockObject              |
| list/utils/model.ts                     | canBecomeSimpleListItem            | \_canBecomeSimpleListItem             |
| list/utils/model.ts                     | isNumberedListType                 | \_isNumberedListType                  |
| list/utils/postfixers.ts                | findAndAddListHeadToMap            | \_findAndAddListHeadToMap             |
| list/utils/postfixers.ts                | fixListIndents                     | \_fixListIndents                      |
| list/utils/postfixers.ts                | fixListItemIds                     | \_fixListItemIds                      |
| list/utils/view.ts                      | isListView                         | \_isListView                          |
| list/utils/view.ts                      | isListItemView                     | \_isListItemView                      |
| list/utils/view.ts                      | getIndent                          | \_getListIndent                       |
| list/utils/view.ts                      | createListElement                  | \_createListElement                   |
| list/utils/view.ts                      | createListItemElement              | \_createListItemElement               |
| list/utils/view.ts                      | getViewElementNameForListType      | \_getViewElementNameForListType       |
| list/utils/view.ts                      | getViewElementIdForListType        | \_getViewElementIdForListType         |
| listproperties/converters.ts            | listPropertiesUpcastConverter      | \_listPropertiesUpcastConverter       |
| listproperties/listpropertiesediting.ts | AttributeStrategy                  | \_ListAttributeConversionStrategy     |
| listproperties/ui/listpropertiesview.ts | ListPropertiesView                 | \_ListPropertiesView                  |
| listproperties/ui/listpropertiesview.ts | StylesView                         | \_ListPropertiesStylesView            |
| listproperties/utils/config.ts          | getNormalizedConfig                | \_getNormalizedListConfig             |
| listproperties/utils/config.ts          | NormalizedListPropertiesConfig     | \_NormalizedListPropertiesConfig      |
| listproperties/utils/style.ts           | getAllSupportedStyleTypes          | \_getAllSupportedListStyleTypes       |
| listproperties/utils/style.ts           | getListTypeFromListStyleType       | \_getListTypeFromListStyleType        |
| listproperties/utils/style.ts           | getListStyleTypeFromTypeAttribute  | \_getListStyleTypeFromTypeAttribute   |
| listproperties/utils/style.ts           | getTypeAttributeFromListStyleType  | \_getTypeAttributeFromListStyleType   |
| listproperties/utils/style.ts           | normalizeListStyle                 | \_normalizeListStyle                  |
| todolist/todocheckboxchangeobserver.ts  | TodoCheckboxChangeObserver         | \_TodoCheckboxChangeObserver          |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-list-multi-level">

#### @ckeditor/ckeditor5-list-multi-level

| file              | original name                  | re-exported name                 |
| ----------------- | ------------------------------ | -------------------------------- |
| multilevellist.ts | MultiLevelListConfig           | \_MultiLevelListConfig           |
| multilevellist.ts | MultiLevelListDefinition       | \_MultiLevelListDefinition       |
| multilevellist.ts | MultiLevelListMarkerDefinition | \_MultiLevelListMarkerDefinition |
| multilevellist.ts | MultiLevelListMarkerPattern    | \_MultiLevelListMarkerPattern    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-markdown-gfm">

#### @ckeditor/ckeditor5-markdown-gfm

| file                | original name    | re-exported name         |
| ------------------- | ---------------- | ------------------------ |
| gfmdataprocessor.ts | GFMDataProcessor | MarkdownGfmDataProcessor |
| html2markdown.ts    | HtmlToMarkdown   | MarkdownGfmHtmlToMd      |
| markdown2html.ts    | MarkdownToHtml   | MarkdownGfmMdToHtml      |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-media-embed">

#### @ckeditor/ckeditor5-media-embed

| file                | original name                    | re-exported name                        |
| ------------------- | -------------------------------- | --------------------------------------- |
| converters.ts       | modelToViewUrlAttributeConverter | \_modelToViewUrlAttributeMediaConverter |
| ui/mediaformview.ts | MediaFormView                    | \_MediaFormView                         |
| utils.ts            | toMediaWidget                    | \_toMediaWidget                         |
| utils.ts            | getSelectedMediaViewWidget       | \_getSelectedMediaViewWidget            |
| utils.ts            | isMediaWidget                    | \_isMediaWidget                         |
| utils.ts            | createMediaFigureElement         | \_createMediaFigureElement              |
| utils.ts            | getSelectedMediaModelWidget      | \_getSelectedMediaModelWidget           |
| utils.ts            | insertMedia                      | \_insertMedia                           |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-mention">

#### @ckeditor/ckeditor5-mention

| file                 | original name          | re-exported name            |
| -------------------- | ---------------------- | --------------------------- |
| mentionconfig.ts     | FeedCallback           | MentionFeedbackCallback     |
| mentionconfig.ts     | ItemRenderer           | MentionItemRenderer         |
| mentionediting.ts    | \_addMentionAttributes | \_addMentionAttributes      |
| mentionediting.ts    | \_toMentionAttribute   | \_toMentionAttribute        |
| mentionui.ts         | createRegExp           | \_createMentionMarkerRegExp |
| ui/domwrapperview.ts | DomWrapperView         | MentionDomWrapperView       |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-merge-fields">

#### @ckeditor/ckeditor5-merge-fields

| file                 | original name     | re-exported name             |
| -------------------- | ----------------- | ---------------------------- |
| mergefieldsconfig.ts | GroupDefinition   | MergeFieldsGroupDefinition   |
| mergefieldsconfig.ts | DataSetDefinition | MergeFieldsDataSetDefinition |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-minimap">

#### @ckeditor/ckeditor5-minimap

| file                          | original name              | re-exported name                 |
| ----------------------------- | -------------------------- | -------------------------------- |
| minimapiframeview.ts          | MinimapIframeView          | \_MinimapIframeView              |
| minimappositiontrackerview.ts | MinimapPositionTrackerView | \_MinimapPositionTrackerView     |
| minimapview.ts                | MinimapViewOptions         | \_MinimapViewOptions             |
| minimapview.ts                | MinimapView                | \_MinimapView                    |
| utils.ts                      | cloneEditingViewDomRoot    | \_cloneMinimapEditingViewDomRoot |
| utils.ts                      | getPageStyles              | \_getMinimapPageStyles           |
| utils.ts                      | getDomElementRect          | \_getMinimapDomElementRect       |
| utils.ts                      | getClientHeight            | \_getMinimapClientHeight         |
| utils.ts                      | getScrollable              | \_getMinimapScrollable           |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-paste-from-office">

#### @ckeditor/ckeditor5-paste-from-office

| file                                  | original name                          | re-exported name                                    |
| ------------------------------------- | -------------------------------------- | --------------------------------------------------- |
| filters/bookmark.ts                   | transformBookmarks                     | \_transformPasteOfficeBookmarks                     |
| filters/br.ts                         | transformBlockBrsToParagraphs          | \_transformPasteOfficeBlockBrsToParagraphs          |
| filters/image.ts                      | replaceImagesSourceWithBase64          | \_replacePasteOfficeImagesSourceWithBase64          |
| filters/image.ts                      | \_convertHexToBase64                   | \_convertHexToBase64                                |
| filters/list.ts                       | transformListItemLikeElementsIntoLists | \_transformPasteOfficeListItemLikeElementsIntoLists |
| filters/list.ts                       | unwrapParagraphInListItem              | \_unwrapPasteOfficeParagraphInListItem              |
| filters/parse.ts                      | parseHtml                              | parsePasteOfficeHtml                                |
| filters/parse.ts                      | ParseHtmlResult                        | PasteOfficeHtmlParseResult                          |
| filters/removeboldwrapper.ts          | removeBoldWrapper                      | \_removePasteOfficeBoldWrapper                      |
| filters/removegooglesheetstag.ts      | removeGoogleSheetsTag                  | \_removePasteGoogleOfficeSheetsTag                  |
| filters/removeinvalidtablewidth.ts    | removeInvalidTableWidth                | \_removePasteOfficeInvalidTableWidths               |
| filters/removemsattributes.ts         | removeMSAttributes                     | \_removePasteMSOfficeAttributes                     |
| filters/removestyleblock.ts           | removeStyleBlock                       | \_removePasteOfficeStyleBlock                       |
| filters/removexmlns.ts                | removeXmlns                            | \_removePasteOfficeXmlnsAttributes                  |
| filters/space.ts                      | normalizeSpacing                       | \_normalizePasteOfficeSpacing                       |
| filters/space.ts                      | normalizeSpacerunSpans                 | \_normalizePasteOfficeSpaceRunSpans                 |
| filters/table.ts                      | transformTables                        | \_transformPasteOfficeTables                        |
| filters/utils.ts                      | convertCssLengthToPx                   | \_convertPasteOfficeCssLengthToPx                   |
| filters/utils.ts                      | isPx                                   | \_isPasteOfficePxValue                              |
| filters/utils.ts                      | toPx                                   | \_toPasteOfficePxValue                              |
| normalizer.ts                         | Normalizer                             | PasteFromOfficeNormalizer                           |
| normalizer.ts                         | NormalizerData                         | PasteFromOfficeNormalizerData                       |
| normalizers/googledocsnormalizer.ts   | GoogleDocsNormalizer                   | PasteFromOfficeGoogleDocsNormalizer                 |
| normalizers/googlesheetsnormalizer.ts | GoogleSheetsNormalizer                 | PasteFromOfficeGoogleSheetsNormalizer               |
| normalizers/mswordnormalizer.ts       | MSWordNormalizer                       | PasteFromOfficeMSWordNormalizer                     |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-real-time-collaboration">

#### @ckeditor/ckeditor5-real-time-collaboration

| file                                             | original name                   | re-exported name                     |
| ------------------------------------------------ | ------------------------------- | ------------------------------------ |
| config.ts                                        | PresenceListConfig              | RtcPresenceListConfig                |
| presencelist/view/presencedropdownlistview.ts    | PresenceDropdownListView        | \_RtcPresenceDropdownListView        |
| presencelist/view/presencedropdownlistview.ts    | PresenceDropdownListWrapperView | \_RtcPresenceDropdownListWrapperView |
| presencelist/view/presencelistview.ts            | PresenceListView                | \_RtcPresenceListView                |
| realtimecollaborativeediting/sessions.ts         | ServerUser                      | RtcServerUser                        |
| realtimecollaborativeediting/sessions.ts         | SessionAddEvent                 | RtcSessionAddEvent                   |
| realtimecollaborativeediting/websocketgateway.ts | WebSocketGateway                | RtcWebSocketGateway                  |
| realtimecollaborativeediting/websocketgateway.ts | ReconnectPlugin                 | RtcReconnectPlugin                   |
| realtimecollaborativeediting/websocketgateway.ts | ReconnectContextPlugin          | RtcReconnectContextPlugin            |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-restricted-editing">

#### @ckeditor/ckeditor5-restricted-editing

| file                                | original name                     | re-exported name                                     |
| ----------------------------------- | --------------------------------- | ---------------------------------------------------- |
| restrictededitingmode/converters.ts | setupExceptionHighlighting        | \_setupRestrictedEditingExceptionHighlighting        |
| restrictededitingmode/converters.ts | resurrectCollapsedMarkerPostFixer | \_resurrectRestrictedEditingCollapsedMarkerPostFixer |
| restrictededitingmode/converters.ts | extendMarkerOnTypingPostFixer     | \_extendRestrictedEditingMarkerOnTypingPostFixer     |
| restrictededitingmode/converters.ts | upcastHighlightToMarker           | \_upcastRestrictedEditingHighlightToMarker           |
| restrictededitingmode/utils.ts      | getMarkerAtPosition               | \_getRestrictedEditingMarkerAtPosition               |
| restrictededitingmode/utils.ts      | isPositionInRangeBoundaries       | \_isRestrictedEditingPositionInRangeBoundaries       |
| restrictededitingmode/utils.ts      | isSelectionInMarker               | \_isRestrictedEditingSelectionInMarker               |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-revision-history">

#### @ckeditor/ckeditor5-revision-history

| file               | original name  | re-exported name           |
| ------------------ | -------------- | -------------------------- |
| revisionhistory.ts | TapeValue      | \_RevisionHistoryTapeValue |
| revisionhistory.ts | TapeItem       | \_RevisionHistoryTapeItem  |
| revisiontracker.ts | RevisionSource | \_RevisionHistorySource    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-special-characters">

#### @ckeditor/ckeditor5-special-characters

| file                                  | original name                   | re-exported name                        |
| ------------------------------------- | ------------------------------- | --------------------------------------- |
| ui/charactergridview.ts               | CharacterGridView               | \_SpecialCharactersGridView             |
| ui/charactergridview.ts               | CharacterGridViewExecuteEvent   | SpecialCharactersGridViewExecuteEvent   |
| ui/charactergridview.ts               | CharacterGridViewTileHoverEvent | SpecialCharactersGridViewTileHoverEvent |
| ui/charactergridview.ts               | CharacterGridViewTileFocusEvent | SpecialCharactersGridViewTileFocusEvent |
| ui/charactergridview.ts               | CharacterGridViewEventData      | SpecialCharactersGridViewEventData      |
| ui/characterinfoview.ts               | CharacterInfoView               | \_SpecialCharacterInfoView              |
| ui/specialcharacterscategoriesview.ts | SpecialCharactersCategoriesView | \_SpecialCharactersCategoriesView       |
| ui/specialcharactersview.ts           | SpecialCharactersView           | \_SpecialCharactersView                 |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-style">

#### @ckeditor/ckeditor5-style

| file                      | original name                                   | re-exported name                                |
| ------------------------- | ----------------------------------------------- | ----------------------------------------------- |
| styleutils.ts             | StyleUtilsIsEnabledForBlockEvent                | StyleUtilsIsEnabledForBlockEvent                |
| styleutils.ts             | StyleUtilsIsActiveForBlockEvent                 | StyleUtilsIsActiveForBlockEvent                 |
| styleutils.ts             | StyleUtilsGetAffectedBlocksEvent                | StyleUtilsGetAffectedBlocksEvent                |
| styleutils.ts             | StyleUtilsIsStyleEnabledForInlineSelectionEvent | StyleUtilsIsStyleEnabledForInlineSelectionEvent |
| styleutils.ts             | StyleUtilsIsStyleActiveForInlineSelectionEvent  | StyleUtilsIsStyleActiveForInlineSelectionEvent  |
| styleutils.ts             | StyleUtilsGetAffectedInlineSelectableEvent      | StyleUtilsGetAffectedInlineSelectableEvent      |
| styleutils.ts             | StyleUtilsGetStylePreviewEvent                  | StyleUtilsGetStylePreviewEvent                  |
| styleutils.ts             | StyleUtilsConfigureGHSDataFilterEvent           | StyleUtilsConfigureGHSDataFilterEvent           |
| ui/stylegridbuttonview.ts | StyleGridButtonView                             | \_StyleGridButtonView                           |
| ui/stylegridview.ts       | StyleGridView                                   | \_StyleGridView                                 |
| ui/stylegroupview.ts      | StyleGroupView                                  | \_StyleGroupView                                |
| ui/stylepanelview.ts      | StylePanelView                                  | \_StylePanelView                                |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-table">

#### @ckeditor/ckeditor5-table

| file                                          | original name                          | re-exported name                             |
| --------------------------------------------- | -------------------------------------- | -------------------------------------------- |
| converters/downcast.ts                        | downcastTable                          | \_downcastTable                              |
| converters/downcast.ts                        | downcastRow                            | \_downcastTableRow                           |
| converters/downcast.ts                        | downcastCell                           | \_downcastTableCell                          |
| converters/downcast.ts                        | convertParagraphInTableCell            | \_convertParagraphInTableCell                |
| converters/downcast.ts                        | isSingleParagraphWithoutAttributes     | \_isSingleTableParagraphWithoutAttributes    |
| converters/downcast.ts                        | DowncastTableOptions                   | \_DowncastTableOptions                       |
| converters/table-caption-post-fixer.ts        | injectTableCaptionPostFixer            | \_injectTableCaptionPostFixer                |
| converters/table-cell-paragraph-post-fixer.ts | injectTableCellParagraphPostFixer      | \_injectTableCellParagraphPostFixer          |
| converters/table-cell-refresh-handler.ts      | tableCellRefreshHandler                | \_tableCellRefreshHandler                    |
| converters/table-headings-refresh-handler.ts  | tableHeadingsRefreshHandler            | \_tableHeadingsRefreshHandler                |
| converters/table-layout-post-fixer.ts         | injectTableLayoutPostFixer             | \_injectTableLayoutPostFixer                 |
| converters/tableproperties.ts                 | upcastStyleToAttribute                 | \_upcastNormalizedTableStyleToAttribute      |
| converters/tableproperties.ts                 | StyleValues                            | \_TableStyleValues                           |
| converters/tableproperties.ts                 | upcastBorderStyles                     | \_upcastTableBorderStyles                    |
| converters/tableproperties.ts                 | downcastAttributeToStyle               | \_downcastTableAttributeToStyle              |
| converters/tableproperties.ts                 | downcastTableAttribute                 | \_downcastTableAttribute                     |
| converters/tableproperties.ts                 | getDefaultValueAdjusted                | \_getDefaultTableValueAdjusted               |
| converters/upcasttable.ts                     | upcastTableFigure                      | \_upcastTableFigure                          |
| converters/upcasttable.ts                     | upcastTable                            | \_upcastTable                                |
| converters/upcasttable.ts                     | skipEmptyTableRow                      | \_skipEmptyTableRow                          |
| converters/upcasttable.ts                     | ensureParagraphInTableCell             | \_ensureParagraphInTableCell                 |
| tablecaption/utils.ts                         | isTable                                | \_isTableModelElement                        |
| tablecaption/utils.ts                         | getCaptionFromTableModelElement        | \_getTableCaptionFromModelElement            |
| tablecaption/utils.ts                         | getCaptionFromModelSelection           | \_getTableCaptionFromModelSelection          |
| tablecaption/utils.ts                         | matchTableCaptionViewElement           | \_matchTableCaptionViewElement               |
| tablecolumnresize/constants.ts                | COLUMN\_MIN\_WIDTH\_AS\_PERCENTAGE     | \_TABLE\_COLUMN\_MIN\_WIDTH\_AS\_PERCENTAGE  |
| tablecolumnresize/constants.ts                | COLUMN\_MIN\_WIDTH\_IN\_PIXELS         | \_TABLE\_COLUMN\_MIN\_WIDTH\_IN\_PIXELS      |
| tablecolumnresize/constants.ts                | COLUMN\_WIDTH\_PRECISION               | \_TABLE\_COLUMN\_WIDTH\_PRECISION            |
| tablecolumnresize/constants.ts                | COLUMN\_RESIZE\_DISTANCE\_THRESHOLD    | \_TABLE\_COLUMN\_RESIZE\_DISTANCE\_THRESHOLD |
| tablecolumnresize/converters.ts               | upcastColgroupElement                  | \_upcastTableColgroupElement                 |
| tablecolumnresize/converters.ts               | downcastTableResizedClass              | \_downcastTableResizedClass                  |
| tablecolumnresize/utils.ts                    | getColumnMinWidthAsPercentage          | \_getTableColumnMinWidthAsPercentage         |
| tablecolumnresize/utils.ts                    | getTableWidthInPixels                  | \_getTableWidthInPixels                      |
| tablecolumnresize/utils.ts                    | getElementWidthInPixels                | \_getElementWidthInPixels                    |
| tablecolumnresize/utils.ts                    | getColumnEdgesIndexes                  | \_getTableColumnEdgesIndexes                 |
| tablecolumnresize/utils.ts                    | toPrecision                            | \_toPrecision                                |
| tablecolumnresize/utils.ts                    | clamp                                  | \_clamp                                      |
| tablecolumnresize/utils.ts                    | createFilledArray                      | \_createFilledArray                          |
| tablecolumnresize/utils.ts                    | sumArray                               | \_sumArray                                   |
| tablecolumnresize/utils.ts                    | normalizeColumnWidths                  | \_normalizeTableColumnWidths                 |
| tablecolumnresize/utils.ts                    | getDomCellOuterWidth                   | \_getDomTableCellOuterWidth                  |
| tablecolumnresize/utils.ts                    | updateColumnElements                   | \_updateTableColumnElements                  |
| tablecolumnresize/utils.ts                    | getColumnGroupElement                  | \_getTableColumnGroupElement                 |
| tablecolumnresize/utils.ts                    | getTableColumnElements                 | \_getTableColumnElements                     |
| tablecolumnresize/utils.ts                    | getTableColumnsWidths                  | \_getTableColumnsWidths                      |
| tablecolumnresize/utils.ts                    | translateColSpanAttribute              | \_translateTableColspanAttribute             |
| tableediting.ts                               | AdditionalSlot                         | TableConversionAdditionalSlot                |
| tablemouse/mouseeventsobserver.ts             | MouseEventsObserver                    | \_TableMouseEventsObserver                   |
| tablemouse/mouseeventsobserver.ts             | ViewDocumentMouseMoveEvent             | ViewDocumentTableMouseMoveEvent              |
| tablemouse/mouseeventsobserver.ts             | ViewDocumentMouseLeaveEvent            | ViewDocumentTableMouseLeaveEvent             |
| ui/colorinputview.ts                          | ColorInputViewOptions                  | \_TableColorInputViewOptions                 |
| ui/colorinputview.ts                          | ColorInputView                         | \_TableColorInputView                        |
| ui/inserttableview.ts                         | InsertTableView                        | \_InsertTableView                            |
| utils/common.ts                               | updateNumericAttribute                 | \_updateTableNumericAttribute                |
| utils/common.ts                               | createEmptyTableCell                   | \_createEmptyTableCell                       |
| utils/common.ts                               | isHeadingColumnCell                    | \_isHeadingColumnCell                        |
| utils/common.ts                               | enableProperty                         | \_enableTableCellProperty                    |
| utils/common.ts                               | getSelectionAffectedTable              | \_getSelectionAffectedTable                  |
| utils/structure.ts                            | cropTableToDimensions                  | \_cropTableToDimensions                      |
| utils/structure.ts                            | getVerticallyOverlappingCells          | \_getVerticallyOverlappingTableCells         |
| utils/structure.ts                            | splitHorizontally                      | \_splitTableCellHorizontally                 |
| utils/structure.ts                            | getHorizontallyOverlappingCells        | \_getHorizontallyOverlappingTableCells       |
| utils/structure.ts                            | splitVertically                        | \_splitTableCellVertically                   |
| utils/structure.ts                            | trimTableCellIfNeeded                  | \_trimTableCellIfNeeded                      |
| utils/structure.ts                            | removeEmptyColumns                     | \_removeEmptyTableColumns                    |
| utils/structure.ts                            | removeEmptyRows                        | \_removeEmptyTableRows                       |
| utils/structure.ts                            | removeEmptyRowsColumns                 | \_removeEmptyTableRowsColumns                |
| utils/structure.ts                            | adjustLastRowIndex                     | \_adjustLastTableRowIndex                    |
| utils/structure.ts                            | adjustLastColumnIndex                  | \_adjustLastTableColumnIndex                 |
| utils/table-properties.ts                     | getSingleValue                         | \_getTableBorderBoxSingleValue               |
| utils/table-properties.ts                     | addDefaultUnitToNumericValue           | \_addDefaultUnitToNumericValue               |
| utils/table-properties.ts                     | NormalizedDefaultProperties            | \_NormalizedTableDefaultProperties           |
| utils/table-properties.ts                     | NormalizeTableDefaultPropertiesOptions | \_NormalizeTableDefaultPropertiesOptions     |
| utils/table-properties.ts                     | getNormalizedDefaultProperties         | \_getNormalizedDefaultTableBaseProperties    |
| utils/table-properties.ts                     | getNormalizedDefaultTableProperties    | \_getNormalizedDefaultTableProperties        |
| utils/table-properties.ts                     | getNormalizedDefaultCellProperties     | \_getNormalizedDefaultTableCellProperties    |
| utils/ui/contextualballoon.ts                 | repositionContextualBalloon            | \_repositionTableContextualBalloon           |
| utils/ui/contextualballoon.ts                 | getBalloonTablePositionData            | \_getBalloonTablePositionData                |
| utils/ui/contextualballoon.ts                 | getBalloonCellPositionData             | \_getBalloonTableCellPositionData            |
| utils/ui/table-properties.ts                  | getBorderStyleLabels                   | \_getBorderTableStyleLabels                  |
| utils/ui/table-properties.ts                  | getLocalizedColorErrorText             | \_getLocalizedTableColorErrorText            |
| utils/ui/table-properties.ts                  | getLocalizedLengthErrorText            | \_getLocalizedTableLengthErrorText           |
| utils/ui/table-properties.ts                  | colorFieldValidator                    | \_colorTableFieldValidator                   |
| utils/ui/table-properties.ts                  | lengthFieldValidator                   | \_lengthTableFieldValidator                  |
| utils/ui/table-properties.ts                  | lineWidthFieldValidator                | \_lineWidthTableFieldValidator               |
| utils/ui/table-properties.ts                  | getBorderStyleDefinitions              | \_getTableOrCellBorderStyleDefinitions       |
| utils/ui/table-properties.ts                  | fillToolbar                            | \_fillTableOrCellToolbar                     |
| utils/ui/table-properties.ts                  | defaultColors                          | \_TABLE\_DEFAULT\_COLORS                     |
| utils/ui/table-properties.ts                  | getLabeledColorInputCreator            | \_getLabeledTableColorInputCreator           |
| utils/ui/widget.ts                            | getSelectionAffectedTableWidget        | \_getSelectionAffectedTableWidget            |
| utils/ui/widget.ts                            | getSelectedTableWidget                 | \_getSelectedTableWidget                     |
| utils/ui/widget.ts                            | getTableWidgetAncestor                 | \_getTableWidgetAncestor                     |

---

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-track-changes">

#### @ckeditor/ckeditor5-track-changes

| file                               | original name           | re-exported name                         |
| ---------------------------------- | ----------------------- | ---------------------------------------- |
| suggestiondescriptionfactory.ts    | Description             | SuggestionDescription                    |
| suggestiondescriptionfactory.ts    | DescriptionCallback     | SuggestionDescriptionCallback            |
| suggestiondescriptionfactory.ts    | LabelCallback           | SuggestionLabelCallback                  |
| suggestiondescriptionfactory.ts    | LabelCallbackObject     | \_SuggestionLabelCallbackObject          |
| trackchangesediting.ts             | renameAttributeKey      | \_TRACK\_CHANGES\_RENAME\_ATTRIBUTE\_KEY |
| trackchangesediting.ts             | FormatData              | SuggestionFormatData                     |
| trackchangesediting.ts             | AttributeData           | SuggestionAttributeData                  |
| ui/view/trackchangespreviewview.ts | TrackChangesPreviewView | \_SuggestionsPreviewView                 |

---

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-typing">

#### @ckeditor/ckeditor5-typing

| file                  | original name                        | re-exported name                           |
| --------------------- | ------------------------------------ | ------------------------------------------ |
| deleteobserver.ts     | DeleteObserver                       | \_DeleteObserver                           |
| inserttextobserver.ts | InsertTextObserver                   | InsertTextObserver                         |
| textwatcher.ts        | TextWatcherMatchedDataEventData      | TextWatcherMatchedTypingDataEventData      |
| textwatcher.ts        | TextWatcherMatchedSelectionEvent     | TextWatcherMatchedTypingSelectionEvent     |
| textwatcher.ts        | TextWatcherMatchedSelectionEventData | TextWatcherMatchedTypingSelectionEventData |
| textwatcher.ts        | TextWatcherUnmatchedEvent            | TextWatcherUnmatchedTypingEvent            |
| typingconfig.ts       | TextTransformationDescription        | TextTypingTransformationDescription        |
| utils/changebuffer.ts | ChangeBuffer                         | TypingChangeBuffer                         |

---

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-ui">

#### @ckeditor/ckeditor5-ui

| file                                   | original name                            | re-exported name                           |
| -------------------------------------- | ---------------------------------------- | ------------------------------------------ |
| bindings/preventdefault.ts             | preventDefault                           | \_preventUiViewDefault                     |
| colorpicker/colorpickerview.ts         | tryParseHexColor                         | \_tryNormalizeHexColor                     |
| colorpicker/utils.ts                   | convertColor                             | \_convertColor                             |
| colorpicker/utils.ts                   | convertToHex                             | \_convertColorToHex                        |
| colorpicker/utils.ts                   | registerCustomElement                    | \_registerCustomElement                    |
| dropdown/menu/dropdownmenubehaviors.ts | DropdownRootMenuBehaviors                | \_DropdownRootMenuBehaviors                |
| dropdown/menu/dropdownmenubehaviors.ts | DropdownMenuBehaviors                    | \_DropdownMenuBehaviors                    |
| menubar/utils.ts                       | MenuBarBehaviors                         | \_MenuBarBehaviors                         |
| menubar/utils.ts                       | MenuBarMenuBehaviors                     | \_MenuBarMenuBehaviors                     |
| menubar/utils.ts                       | MenuBarMenuViewPanelPositioningFunctions | \_MenuBarMenuViewPanelPositioningFunctions |
| menubar/utils.ts                       | processMenuBarConfig                     | \_processMenuBarConfig                     |
| model.ts                               | Model                                    | UIModel                                    |
| panel/balloon/contextualballoon.ts     | RotatorView                              | \_ContextualBalloonRotatorView             |
| search/searchinfoview.ts               | SearchInfoView                           | \_SearchInfoView                           |
| search/text/searchtextqueryview.ts     | SearchTextQueryView                      | \_SearchTextQueryView                      |
| template.ts                            | RenderData                               | \_TemplateRenderData                       |
| toolbar/toolbarview.ts                 | NESTED\_TOOLBAR\_ICONS                   | NESTED\_TOOLBAR\_ICONS                     |
| toolbar/toolbarview.ts                 | ToolbarBehavior                          | \_ToolbarBehavior                          |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-undo">

#### @ckeditor/ckeditor5-undo

| file           | original name | re-exported name    |
| -------------- | ------------- | ------------------- |
| basecommand.ts | BaseCommand   | UndoRedoBaseCommand |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-upload">

#### @ckeditor/ckeditor5-upload

| file          | original name | re-exported name |
| ------------- | ------------- | ---------------- |
| filereader.ts | FileReader    | FileReader       |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-utils">

#### @ckeditor/ckeditor5-utils

| file                             | original name                    | re-exported name                   |
| -------------------------------- | -------------------------------- | ---------------------------------- |
| areconnectedthroughproperties.ts | areConnectedThroughProperties    | areConnectedThroughProperties      |
| ckeditorerror.ts                 | DOCUMENTATION\_URL               | DOCUMENTATION\_URL                 |
| dom/getcommonancestor.ts         | getCommonAncestor                | getCommonAncestor                  |
| dom/getpositionedancestor.ts     | getPositionedAncestor            | getPositionedAncestor              |
| dom/global.ts                    | GlobalType                       | GlobalType                         |
| dom/global.ts                    | globalVar                        | global                             |
| dom/iswindow.ts                  | isWindow                         | isWindow                           |
| dom/position.ts                  | Options                          | DomOptimalPositionOptions          |
| dom/position.ts                  | PositioningFunctionResult        | DomPositioningFunctionResult       |
| dom/rect.ts                      | RectLike                         | DomRectLike                        |
| env.ts                           | getUserAgent                     | \_getUserAgent                     |
| env.ts                           | isMac                            | \_isMac                            |
| env.ts                           | isWindows                        | \_isWindows                        |
| env.ts                           | isGecko                          | \_isGecko                          |
| env.ts                           | isSafari                         | \_isSafari                         |
| env.ts                           | isiOS                            | \_isiOS                            |
| env.ts                           | isAndroid                        | \_isAndroid                        |
| env.ts                           | isBlink                          | \_isBlink                          |
| env.ts                           | isRegExpUnicodePropertySupported | \_isRegExpUnicodePropertySupported |
| env.ts                           | isMediaForcedColors              | \_isMediaForcedColors              |
| env.ts                           | isMotionReduced                  | \_isMotionReduced                  |
| mapsequal.ts                     | mapsEqual                        | mapsEqual                          |
| nth.ts                           | nth                              | nth                                |
| objecttomap.ts                   | objectToMap                      | objectToMap                        |
| spy.ts                           | spy                              | spy                                |
| translation-service.ts           | \_clear                          | \_clearTranslations                |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-watchdog">

#### @ckeditor/ckeditor5-watchdog

| file               | original name             | re-exported name                 |
| ------------------ | ------------------------- | -------------------------------- |
| contextwatchdog.ts | WatchdogItemConfiguration | ContextWatchdogItemConfiguration |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-widget">

#### @ckeditor/ckeditor5-widget

| file                         | original name                      | re-exported name                             |
| ---------------------------- | ---------------------------------- | -------------------------------------------- |
| highlightstack.ts            | HighlightStack                     | WidgetHighlightStack                         |
| highlightstack.ts            | HighlightStackChangeEvent          | WidgetHighlightStackChangeEvent              |
| highlightstack.ts            | HighlightStackChangeEventData      | WidgetHighlightStackChangeEventData          |
| verticalnavigation.ts        | verticalNavigationHandler          | verticalWidgetNavigationHandler              |
| widgetresize.ts              | ResizerOptions                     | WidgetResizerOptions                         |
| widgetresize/resizer.ts      | Resizer                            | WidgetResizer                                |
| widgetresize/resizer.ts      | ResizerBeginEvent                  | WidgetResizerBeginEvent                      |
| widgetresize/resizer.ts      | ResizerCancelEvent                 | WidgetResizerCancelEvent                     |
| widgetresize/resizer.ts      | ResizerCommitEvent                 | WidgetResizerCommitEvent                     |
| widgetresize/resizer.ts      | ResizerUpdateSizeEvent             | WidgetResizerUpdateSizeEvent                 |
| widgetresize/resizerstate.ts | ResizeState                        | WidgetResizeState                            |
| widgetresize/sizeview.ts     | SizeView                           | \_WidgetSizeView                             |
| widgettypearound/utils.ts    | TYPE\_AROUND\_SELECTION\_ATTRIBUTE | \_WIDGET\_TYPE\_AROUND\_SELECTION\_ATTRIBUTE |
| widgettypearound/utils.ts    | isTypeAroundWidget                 | isTypeAroundWidget                           |
| widgettypearound/utils.ts    | getClosestTypeAroundDomButton      | \_getClosestWidgetTypeAroundDomButton        |
| widgettypearound/utils.ts    | getTypeAroundButtonPosition        | \_getWidgetTypeAroundButtonPosition          |
| widgettypearound/utils.ts    | getClosestWidgetViewElement        | \_getClosestWidgetViewElement                |
| widgettypearound/utils.ts    | getTypeAroundFakeCaretPosition     | \_getWidgetTypeAroundFakeCaretPosition       |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-word-count">

#### @ckeditor/ckeditor5-word-count

| file     | original name           | re-exported name          |
| -------- | ----------------------- | ------------------------- |
| utils.ts | modelElementToPlainText | \_modelElementToPlainText |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--new-exports">

### New exports

Listed below are exports introduced with NIM.

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-ai-2">

#### @ckeditor/ckeditor5-ai

| file                          | exported name        |
| ----------------------------- | -------------------- |
| adapters/openaitextadapter.ts | AIRequestMessageItem |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-case-change-2">

#### @ckeditor/ckeditor5-case-change

| file                 | exported name               |
| -------------------- | --------------------------- |
| casechangecommand.ts | CaseChangeTransformCallback |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-collaboration-core-2">

#### @ckeditor/ckeditor5-collaboration-core

| file     | exported name          |
| -------- | ---------------------- |
| users.ts | CollaborationUserColor |
| users.ts | CollaborationUserData  |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-comments-2">

#### @ckeditor/ckeditor5-comments

| file                           | exported name            |
| ------------------------------ | ------------------------ |
| annotations/annotation.ts      | AnnotationTargetBase     |
| comments/commentsrepository.ts | CommentPermissionsConfig |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-import-word-2">

#### @ckeditor/ckeditor5-import-word

| file                 | exported name                 |
| -------------------- | ----------------------------- |
| importwordcommand.ts | ImportWordDataInsertEventData |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-real-time-collaboration-2">

#### @ckeditor/ckeditor5-real-time-collaboration

| file                                             | exported name |
| ------------------------------------------------ | ------------- |
| realtimecollaborativeediting/websocketgateway.ts | RtcReconnect  |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-track-changes-2">

#### @ckeditor/ckeditor5-track-changes

| file                            | exported name             |
| ------------------------------- | ------------------------- |
| suggestiondescriptionfactory.ts | SuggestionDescriptionItem |
| trackchangesconfig.ts           | TrackChangesPreviewConfig |
| trackchangesdata.ts             | TrackChangesDataGetter    |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-uploadcare">

#### @ckeditor/ckeditor5-uploadcare

| file                                         | exported name          |
| -------------------------------------------- | ---------------------- |
| uploadcareconfig.ts                          | UploadcareExcludedKeys |
| uploadcareimageedit/uploadcareimageeditui.ts | UploadcareImageCache   |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-engine-2">

#### @ckeditor/ckeditor5-engine

| file                             | exported name              |
| -------------------------------- | -------------------------- |
| conversion/conversion.ts         | ConversionType             |
| conversion/downcastdispatcher.ts | DowncastDispatcherEventMap |
| view/domconverter.ts             | ViewBlockFillerMode        |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-table-2">

#### @ckeditor/ckeditor5-table

| file          | exported name      |
| ------------- | ------------------ |
| tableutils.ts | TableIndexesObject |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-ui-2">

#### @ckeditor/ckeditor5-ui

| file                                      | exported name                    |
| ----------------------------------------- | -------------------------------- |
| arialiveannouncer.ts                      | AriaLiveAnnouncerPolitenessValue |
| arialiveannouncer.ts                      | AriaLiveAppendContentAttributes  |
| arialiveannouncer.ts                      | AriaLiveAnnounceConfig           |
| button/filedialogbuttonview.ts            | FileDialogViewMixin              |
| button/filedialogbuttonview.ts            | FileDialogButtonViewBase         |
| colorpicker/colorpickerview.ts            | SliderView                       |
| colorpicker/colorpickerview.ts            | ColorPickerInputRowView          |
| editableui/inline/inlineeditableuiview.ts | InlineEditableUIViewOptions      |
| template.ts                               | AttributeValues                  |
| toolbar/toolbarview.ts                    | ItemsView                        |
| editorui/poweredby.ts                     | PoweredByConfig                  |

<a id="ckeditor5/latest/updating/nim-migration/migrating-imports.html--ckeditorckeditor5-utils-2">

#### @ckeditor/ckeditor5-utils

| file                 | exported name             |
| -------------------- | ------------------------- |
| crc32.ts             | CRCValue                  |
| dom/createelement.ts | HTMLElementAttributes     |
| dom/createelement.ts | SVGElementAttributes      |
| dom/createelement.ts | ChildrenElements          |
| dom/scroll.ts        | IfTrue                    |
| observablemixin.ts   | ObservableSingleBindChain |
| observablemixin.ts   | ObservableDualBindChain   |
| observablemixin.ts   | ObservableMultiBindChain  |

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html">source file: "ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html"</a>

## Migrating to new installation methods

In this guide, we will explore the new installation methods introduced in CKEditor 5 v42.0.0\. These methods make CKEditor 5 much easier to use by reducing the number of possible installation paths and removing most of the limitations of the old methods. Links to migration guides for specific installation methods can be found in the table of contents on the left or under the **main menu button in the upper-left corner** on mobile and at the end of this document.

Let’s start by comparing the new installation methods to the old ones to better understand what has changed.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--legacy-installation-methods">

### Legacy installation methods

Prior to version 42.0.0, there were several ways to install CKEditor 5, each with its own limitations and quirks that made it difficult or impossible to use in certain scenarios. It was also difficult for us to properly document all possible setups without making the documentation overly complex, as these setups were so different from each other.

Here is a code example showing one of the possible setups using the old installation methods:

```
// webpack.config.js
const path = require( 'path' );
const { CKEditorTranslationsPlugin } = require( '@ckeditor/ckeditor5-dev-translations' );
const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

module.exports = {
    entry: './src/index.js',
    output: {
        path: path.resolve( __dirname, 'dist' ),
        filename: 'bundle.js'
    },
    plugins: [
        new CKEditorTranslationsPlugin( {
            language: 'en'
        } )
    ],
    module: {
        rules: [
            {
                test: /\.svg$/,
                use: [ 'raw-loader' ]
            },
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag',
                            attributes: {
                                'data-cke': true
                            }
                        }
                    },
                    'css-loader',
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: styles.getPostCssConfig( {
                                minify: true
                            } )
                        }
                    }
                ]
            }
        ]
    }
};

```

```
// src/index.js
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { Mention } from '@ckeditor/ckeditor5-mention';
import { FormatPainter } from '@ckeditor/ckeditor5-format-painter';
import { SlashCommand } from '@ckeditor/ckeditor5-slash-command';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<YOUR_LICENSE_KEY>',

        // This value must be kept in sync with the language defined in webpack.config.js.
        language: 'en'
    } );

```

It may seem strange to show the webpack configuration in an example of the old installation methods, but it was a necessary part of the setup to handle translations, CSS, and SVG files. This setup could be even more complex if you wanted to use TypeScript.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--new-installation-methods">

### New installation methods

In the new installation methods we have reduced the number of possible paths to just two: **npm packages and browser builds**. Unlike before, both methods no longer require you to add dozens of individual packages or JavaScript bundles to get the editor up and running. Instead, you can import the editor and all our open source plugins from the `ckeditor5` package and the premium features from `ckeditor5-premium-features`. You also do not need to worry about a specific webpack or Vite configurations, as the new installation methods are designed to work out-of-the-box with any modern bundler or JavaScript meta-framework like Next.js.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--npm-packages">

#### npm packages

The new npm packages are the recommended way to install CKEditor 5 if you use a module bundler like Vite or webpack or one of the popular JavaScript meta-frameworks.

This is what the new npm setup looks like when using the open-source and commercial features and translations:

```
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from 'ckeditor5';
import { FormatPainter, SlashCommand } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<YOUR_LICENSE_KEY>',
        translations: [
            coreTranslations,
            premiumFeaturesTranslations
        ]
    } );

```

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--browser-builds">

#### Browser builds

The browser builds are a great way to use CKEditor 5 if you do not want to build JavaScript with a module bundler. The browser builds are available as JavaScript modules and can be loaded directly in the browser using the `<script type="module">` tag.

Here is the same editor setup as above, but using the browser builds:

```
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

<script type="importmap">
{
    "imports": {
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",
        "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.js",
        "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/"
    }
}
</script>

<script type="module">
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } from 'ckeditor5';
import { FormatPainter, SlashCommand } from 'ckeditor5-premium-features';

import coreTranslations from 'ckeditor5/translations/pl.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/pl.js';

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<YOUR_LICENSE_KEY>',
        translations: [
            coreTranslations,
            premiumFeaturesTranslations
        ]
    } );
</script>

```

In some environments, you may not be able to use the import maps or JavaScript modules. In such cases, you can use the UMD builds instead. These register global variables that you can use in your scripts. This is the same setup as above, but using the UMD builds:

```
<!-- Style sheets -->
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />

<!-- Scripts -->
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>

<!-- Translations -->
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/translations/pl.umd.js"></script>
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/translations/pl.umd.js"></script>

<script>
const { ClassicEditor, Essentials, Bold, Italic, Paragraph, Mention } = CKEDITOR;
const { FormatPainter, SlashCommand } = CKEDITOR_PREMIUM_FEATURES;

ClassicEditor
    .create( {
        attachTo: document.querySelector( '#editor' ),
        plugins: [ Essentials, Bold, Italic, Paragraph, Mention, FormatPainter, SlashCommand ],
        toolbar: [ /* ... */ ],
        licenseKey: '<YOUR_LICENSE_KEY>'
    } );
</script>

```

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--whats-new">

#### What’s new?

There are a few things that stand out in both examples compared to the old installation methods:

1. Everything is imported from the `ckeditor5` and `ckeditor5-premium-features` packages only. In the browser, this is done using [importmaps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap), which maps the package names to the build URLs.
2. CSS files are imported separately from the JavaScript files, which improves performance and allows you to more easily customize or remove the default editor styles.
3. Translations are imported as JavaScript objects and passed to the editor instance, instead of using side-effect imports (`import '...'`) that rely on the global state.
4. You no longer need to maintain a CKEditor 5-specific webpack or Vite configuration, and can use CKEditor 5 with any modern bundler or JavaScript meta-framework.

The setups we presented above are what you should aim for when migrating your project to the new installation methods.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--feature-comparison">

#### Feature comparison

Here is a visual comparison of the features available in the new npm and CDN builds and the old installation methods:

| Installation methods                           | New methods | Legacy methods |        |          |   |
| ---------------------------------------------- | ----------- | -------------- | ------ | -------- | - |
| npm                                            | CDN         | Predefined     | Custom | DLL      |   |
| No build step                                  | ❌           | ✅              | ✅      | ❌        | ✅ |
| Can be used with any modern bundler            | ✅           | ✅              | ✅      | ❌        | ❌ |
| Allows adding plugins                          | ✅           | ✅              | ❌      | ✅        | ✅ |
| Style customization                            | ✅           | ✅              | ❌      | ⚠️ \[1\] | ❌ |
| Icon customization                             | ✅           | ❌              | ❌      | ✅        | ❌ |
| Does not rely on global state                  | ✅           | ✅              | ❌      | ❌        | ❌ |
| Provides editor- and content-only style sheets | ✅           | ✅              | ❌      | ❌        | ❌ |
| Style sheets separate from JavaScript          | ✅           | ✅              | ❌      | ⚠️\[2\]  | ❌ |
| Can be optimized to reduce bundle size         | ✅           | ❌              | ❌      | ✅        | ✅ |

\[1\] Style customization is partially supported via webpack configuration.  
\[2\] CSS can be separated from JavaScript using custom webpack configuration.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--sunset-of-old-installation-methods-and-deprecation-timelines">

### Sunset of old installation methods and deprecation timelines

With the release of version 42.0.0, we have decided to deprecate the older methods of setting up CKEditor 5\. The new experience introduced in v42.0.0 is far superior.

However, we understand that migrating to a new setup, even if easy, requires planning and work allocation. We would rather not block anyone from receiving bug fixes and improvements due to a deprecated update path. Therefore, we will support all existing methods according to the timelines given below.

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--deprecation-of-the-predefined-builds">

#### Deprecation of the predefined builds

Our provided predefined editor builds, such as `ckeditor5-build-classic`, were supported until **the end of Q1 (March), 2025**.

What we sunset on this date:

1. The documentation for the predefined builds and superbuild was removed.
2. No more new versions of predefined builds packages are published to npm.
3. We updated our environment to target ES2022, thus dropping the support for webpack 4.

See the [migration guide](#ckeditor5/latest/updating/nim-migration/predefined-builds.html).

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--deprecation-of-the-custom-builds">

#### Deprecation of the custom builds

The setup method which was “webpack-first”, in which you imported from specific packages from `src` folder, will be supported until **the end of Q1 (March), 2026**.

What we will sunset on this date:

1. The documentation for the custom builds will be removed.
2. New npm package versions will no longer include the `src` directory. Instead, the `dist` directory will become the primary entry point for importing files, and all imports will happen through the package’s index.
3. Deprecation of `@ckeditor/ckeditor5-dev-translations` package, as it will not be needed anymore.
4. Still to be decided, but we may deprecate loading translations from the `CKEDITOR_TRANSLATIONS` global, as new installation methods enable and promote doing it through the editor’s configuration.

See the [migration guide](#ckeditor5/latest/updating/nim-migration/customized-builds.html).

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--deprecation-of-dlls">

#### Deprecation of DLLs

This is an advanced setup method that we provided, that was used to dynamically create the editor and its configuration on the browser side. As this is now provided out-of-the-box with our browser builds, this method will also be deprecated. As DLLs are used in complex CMSes, this deprecation timeline is significantly longer.

The DLLs will be supported until **the end of Q1 (March), 2026**.

What we will sunset on this date:

1. The documentation for DLLs will be removed.
2. New versions of npm packages published after this date will not have `build` directory.

See the [migration guide](#ckeditor5/latest/updating/nim-migration/dll-builds.html).

<a id="ckeditor5/latest/updating/nim-migration/migration-to-new-installation-methods.html--migrating-from-the-old-installation-methods">

### Migrating from the old installation methods

To migrate your project to the new installation methods, you can follow the instructions below.

First, if you maintain any CKEditor 5 custom plugins as separate packages, whether in a monorepo setup or published to npm, you need to migrate them:

* [Migrating custom plugins](#ckeditor5/latest/updating/nim-migration/custom-plugins.html).

Second, proceed with migrating your project, depending on the old installation method you are using.

* [Migrating from predefined builds](#ckeditor5/latest/updating/nim-migration/predefined-builds.html).
* [Migrating from legacy Online Builder](#ckeditor5/latest/updating/nim-migration/online-builder.html).
* [Migrating from customized builds](#ckeditor5/latest/updating/nim-migration/customized-builds.html).
* [Migrating from DLL builds](#ckeditor5/latest/updating/nim-migration/dll-builds.html).

Finally, if you use our React, Vue or Angular integrations, you also need to update them:

* Update the `@ckeditor/ckeditor5-react` package to version `^8.0.0`. Please refer to the [package’s changelog](https://github.com/ckeditor/ckeditor5-react/blob/master/CHANGELOG.md), because of the minor breaking change introduced in this version.
* Update the `@ckeditor/ckeditor5-vue` package to version `^6.0.0`.
* Update the `@ckeditor/ckeditor5-angular` package to version `^8.0.0`.

If you encounter any issues during the migration process, please refer to this [GitHub issue containing common errors](https://github.com/ckeditor/ckeditor5/issues/16511). If your issue is not listed there, feel free to open a new issue in our [GitHub repository](https://github.com/ckeditor/ckeditor5/issues/new/choose).

<a id="ckeditor5/latest/updating/nim-migration/online-builder.html">source file: "ckeditor5/latest/updating/nim-migration/online-builder.html"</a>

## Migrating from legacy Online Builder

There are three installation methods you can migrate to from the legacy Online Builder. The best option for you depends on whether you just want an out-of-the-box browser build, or if you want a customized and optimized build.

The npm package is the most flexible and powerful way to install CKEditor 5\. It allows you to create a custom build of the editor with only the features you need, thus significantly reducing the final size of the build. However, you will need a JavaScript bundler or meta-framework to create such a build.

If you do not want a build process, you can either use our CDN build or download the ZIP archive. Both of these include the editor and all plugins, so you can use all the features of CKEditor 5 without setting up a build process.

<a id="ckeditor5/latest/updating/nim-migration/online-builder.html--cdn-build">

### CDN build

The CDN build is a good option to quickly add CKEditor 5 to your website without installing any dependencies or setting up a build process. We recommend using our new interactive [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) to customize the build to your needs. Then, in the `Installation` section of the Builder, you can select the `Cloud (CDN)` option to learn how to add the editor to your website.

<a id="ckeditor5/latest/updating/nim-migration/online-builder.html--zip-archive">

### ZIP archive

If you do not want to have a build process or use our CDN build, you can download a ZIP archive with the editor build. We recommend using our new interactive [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) to customize the build to your needs. Then, in the `Installation` section of the Builder, you can select the `Self-hosted (ZIP)` option to learn how to add the editor to your website.

<a id="ckeditor5/latest/updating/nim-migration/online-builder.html--npm-package">

### npm package

If you decide to use the npm package, you can either use our new interactive [Builder](https://ckeditor.com/ckeditor-5/builder/?redirect=docs) to create a new build, or you can update your existing project from the legacy Online Builder. **We recommend using the new interactive Builder**, but if you want to keep your existing build, you can follow the steps below.

1. Follow the steps in the [Migrating from customized builds](#ckeditor5/latest/updating/nim-migration/customized-builds.html) guide.
2. Once this is done, remove the old `build` folder and run the following command to create a new build of CKEditor 5.

```
npm run build

```

1. There should be three files in the new `build` folder:

  * `ckeditor.d.ts`,
  * `ckeditor.js`,
  * `ckeditor.js.map`.  
Now you can start to remove some unused webpack plugins and update the `webpack.config.js` file.
2. Uninstall the following `devDependencies`:

```
npm uninstall \
@ckeditor/ckeditor5-dev-translations \
@ckeditor/ckeditor5-dev-utils \
@ckeditor/ckeditor5-theme-lark\
css-loader \
postcss \
postcss-loader \
raw-loader \
style-loader \
terser-webpack-plugin

```

1. Install the following packages:

```
npm install --save-dev \
css-loader \
css-minimizer-webpack-plugin \
mini-css-extract-plugin \
terser-webpack-plugin

```

1. Update the `webpack.config.js` file:

```
'use strict';

/* eslint-env node */

const path = require( 'path' );
const TerserWebpackPlugin = require( 'terser-webpack-plugin' );
const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' );
const CssMinimizerPlugin = require( 'css-minimizer-webpack-plugin' );

module.exports = {
devtool: 'source-map',
performance: { hints: false },

entry: path.resolve( __dirname, 'src', 'ckeditor.ts' ),

output: {
    // The name under which the editor will be exported.
    library: 'ClassicEditor',

    path: path.resolve( __dirname, 'build' ),
    filename: 'ckeditor.js',
    libraryTarget: 'umd',
    libraryExport: 'default'
},

optimization: {
    minimize: true,
    minimizer: [
        new CssMinimizerPlugin(),
        new TerserWebpackPlugin( {
            terserOptions: {
                output: {
                    // Preserve CKEditor&nbsp;5 license comments.
                    comments: /^!/
                }
            },
            extractComments: false
        } )
    ]
},

plugins: [
    new MiniCssExtractPlugin( {
        filename: 'ckeditor.css'
    } ),
],

resolve: {
    extensions: [ '.ts', '.js', '.json' ]
},

module: {
    rules: [
        {
            test: /\.ts$/,
            use: 'ts-loader'
        },
        {
            test: /\.css$/i,
            use: [ MiniCssExtractPlugin.loader, 'css-loader' ]
        }
    ]
}
};

```

1. Add the following line to the `sample/index.html` file before other CSS files:

```
<link rel="stylesheet" type="text/css" href="../build/ckeditor.css">

```

1. Delete the old `build` folder and run the following command to create a new build of CKEditor 5.

```
npm run build

```

1. There should be five files in the new `build` folder:

  * `ckeditor.css`,
  * `ckeditor.css.map`,
  * `ckeditor.d.ts`,
  * `ckeditor.js`,
  * `ckeditor.js.map`.

The new build has two more files because the CSS is now separated from the JavaScript file, which should improve performance compared to the old approach. When updating your project that uses the `build` folder, remember to import this new CSS file as well.

Additionally, both the JavaScript and CSS files are now minified, potentially improving performance.

If you want to optimize the build further, follow the steps from the [Optimizing build size](#ckeditor5/latest/getting-started/setup/optimizing-build-size.html) guide.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html">source file: "ckeditor5/latest/updating/nim-migration/predefined-builds.html"</a>

## Migrating from predefined builds

Before version 42.0.0, the predefined builds were the easiest way to get started with CKEditor 5\. They provided an out-of-the-box editor with a predefined set of plugins and a default configuration. However, they had limitations, such as the inability to customize the editor by adding or removing plugins.

The new installation methods solve this problem. They allow you to fully customize the editor, whether you use npm packages or browser builds.

Migrating from the predefined builds to the new installation methods should mostly be a matter of copying and pasting the code below to replace the old code. The code to copy depends on the build and distribution method you used.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--prerequisites">

### Prerequisites

Before you start, follow the usual upgrade path to update your project to use the latest version of CKEditor 5\. This will rule out any problems that may be caused by upgrading from an outdated version of CKEditor 5.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--migration-steps">

### Migration steps

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--npm">

#### npm

If you are using predefined builds from npm, follow the steps below:

1. Start by uninstalling the old build package. It can be identified by the `@ckeditor/ckeditor5-build-` prefix. For example, if you were using the `@ckeditor/ckeditor5-build-classic` package, you should uninstall it. Below is the command to uninstall all predefined builds.  
```  
npm uninstall \  
    @ckeditor/ckeditor5-build-balloon \  
    @ckeditor/ckeditor5-build-balloon-block \  
    @ckeditor/ckeditor5-build-classic \  
    @ckeditor/ckeditor5-build-decoupled-document \  
    @ckeditor/ckeditor5-build-inline \  
    @ckeditor/ckeditor5-build-multi-root  
```
2. Next, install the `ckeditor5` package. This package contains the editor and all of our open-source plugins.  
```  
npm install ckeditor5  
```
3. (Optional) If you are using premium features from our commercial offer, you should also install the `ckeditor5-premium-features` package.  
```  
npm install ckeditor5-premium-features  
```
4. Open the file where you initialized the editor. Then replace the import statement and the initialization code depending on the build you are using.  
Classic editor  
Before:  
```  
import ClassicEditor from '@ckeditor/ckeditor5-build-classic';  
ClassicEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    ClassicEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
class Editor extends ClassicEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
Inline editor  
Before:  
```  
import InlineEditor from '@ckeditor/ckeditor5-build-inline';  
InlineEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    InlineEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
class Editor extends InlineEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
Balloon editor  
Before:  
```  
import BalloonEditor from '@ckeditor/ckeditor5-build-balloon';  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
Balloon block editor  
Before:  
```  
import BalloonEditor from '@ckeditor/ckeditor5-build-balloon-block';  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    BlockToolbar,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
/*  
Create an additional stylesheet file with the given content:  
.ck.ck-block-toolbar-button {  
    transform: translateX( calc(-1 * var(--ck-spacing-large)) );  
}
*/  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        BlockToolbar,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        blockToolbar: [  
            'undo', 'redo',  
            '|', 'heading',  
            '|', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
            '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
        ],  
        toolbar: {  
            items: [  
                'bold', 'italic', 'link'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
Decoupled document editor  
Before:  
```  
import DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';  
DecoupledEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    DecoupledEditor,  
    Essentials,  
    Alignment,  
    FontSize,  
    FontFamily,  
    FontColor,  
    FontBackgroundColor,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    Strikethrough,  
    Underline,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageResize,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    IndentBlock,  
    Link,  
    List,  
    ListProperties,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
class Editor extends DecoupledEditor {  
    static builtinPlugins = [  
        Essentials,  
        Alignment,  
        FontSize,  
        FontFamily,  
        FontColor,  
        FontBackgroundColor,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        Strikethrough,  
        Underline,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageResize,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        IndentBlock,  
        Link,  
        List,  
        ListProperties,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',  
                '|', 'bold', 'italic', 'underline', 'strikethrough',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'alignment',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            resizeUnit: 'px',  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:wrapText',  
                'imageStyle:breakText',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        list: {  
            properties: {  
                styles: true,  
                startIndex: true,  
                reversed: true  
            }  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
Multi-root editor  
Before:  
```  
import MultiRootEditor from '@ckeditor/ckeditor5-build-multi-root';  
MultiRootEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```  
After:  
```  
import {  
    MultiRootEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
import 'ckeditor5/ckeditor5.css';  
class Editor extends MultiRootEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
```
5. Unlike when using predefined builds, you are now free to customize the editor by adding or removing plugins. However, before you do this, you should test the editor to make sure it works as expected.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--cdn">

#### CDN

If you are using the predefined builds from CDN, follow the steps below depending on whether you want to use JavaScript modules (ESM) with imports or standard (UMD) scripts with global variables.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--cdn-with-imports">

##### CDN with imports

One notable difference between the old build and the new ESM build is that the former uses the `<script>` tags while the latter uses the `<script type="module">` tags, which behave differently in some cases. For more information, see this [MDN page explaining the differences between modules and standard scripts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#other%5Fdifferences%5Fbetween%5Fmodules%5Fand%5Fstandard%5Fscripts).

1. Start by removing the `<script>` tags that contain the old build.  
```  
<script src="https://cdn.ckeditor.com/ckeditor5/<VERSION>/classic/ckeditor.js"></script>  
```
2. Add the `<link>` tags to include the editor’s CSS files and the `<script type="importmap">` tag to map the package names to the build URLs.

2.1 If you only use the open-source features:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<script type="importmap">  
{  
    "imports": {  
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",  
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"  
    }  
}  
</script>  
```

2.2 If you also use premium features from our commercial offer:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />  
<script type="importmap">  
{  
    "imports": {  
        "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",  
        "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/",  
        "ckeditor5-premium-features": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.js",  
        "ckeditor5-premium-features/": "https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/"  
    }  
}  
</script>  
```
3. Replace the old `<script>` tag, which contains the initialization code, depending on the build you are using.  
Classic editor  
Before:  
```  
<script>  
ClassicEditor  
    .create( {  
        attachTo: document.querySelector( '#editor' ),  
        // ... other config  
    } )  
    .catch( error => {  
            console.error( error );  
    } );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    ClassicEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
class Editor extends ClassicEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Inline editor  
Before:  
```  
<script>  
InlineEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    InlineEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
class Editor extends InlineEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Balloon editor  
Before:  
```  
<script>  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Balloon block editor  
Before:  
```  
<script>  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    BlockToolbar,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
/*  
Create an additional stylesheet file with the given content:  
.ck.ck-block-toolbar-button {  
    transform: translateX( calc(-1 * var(--ck-spacing-large)) );  
}
*/  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        BlockToolbar,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        blockToolbar: [  
            'undo', 'redo',  
            '|', 'heading',  
            '|', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
            '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
        ],  
        toolbar: {  
            items: [  
                'bold', 'italic', 'link'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Decoupled document editor  
Before:  
```  
<script>  
DecoupledEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    DecoupledEditor,  
    Essentials,  
    Alignment,  
    FontSize,  
    FontFamily,  
    FontColor,  
    FontBackgroundColor,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    Strikethrough,  
    Underline,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageResize,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    IndentBlock,  
    Link,  
    List,  
    ListProperties,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
class Editor extends DecoupledEditor {  
    static builtinPlugins = [  
        Essentials,  
        Alignment,  
        FontSize,  
        FontFamily,  
        FontColor,  
        FontBackgroundColor,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        Strikethrough,  
        Underline,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageResize,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        IndentBlock,  
        Link,  
        List,  
        ListProperties,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',  
                '|', 'bold', 'italic', 'underline', 'strikethrough',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'alignment',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            resizeUnit: 'px',  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:wrapText',  
                'imageStyle:breakText',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        list: {  
            properties: {  
                styles: true,  
                startIndex: true,  
                reversed: true  
            }  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Multi-root editor  
Before:  
```  
<script>  
MultiRootEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    MultiRootEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} from 'ckeditor5';  
class Editor extends MultiRootEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Superbuild  
Before:  
```  
<script>  
ClassicEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script type="module">  
import {  
    ClassicEditor as ClassicEditorBase,  
    InlineEditor as InlineEditorBase,  
    BalloonEditor as BalloonEditorBase,  
    DecoupledEditor as DecoupledEditorBase,  
    CKFinderUploadAdapter,  
    Alignment,  
    Autoformat,  
    Bold,  
    Italic,  
    Underline,  
    Strikethrough,  
    Superscript,  
    Subscript,  
    Code,  
    BlockQuote,  
    CKBox,  
    CKBoxImageEdit,  
    CKFinder,  
    CloudServices,  
    CodeBlock,  
    Essentials,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    AutoImage,  
    ImageResize,  
    ImageUpload,  
    ImageInsert,  
    PictureEditing,  
    Indent,  
    IndentBlock,  
    TextPartLanguage,  
    Link,  
    AutoLink,  
    LinkImage,  
    List,  
    ListProperties,  
    TodoList,  
    MediaEmbed,  
    Paragraph,  
    FindAndReplace,  
    FontBackgroundColor,  
    FontColor,  
    FontFamily,  
    FontSize,  
    Highlight,  
    HorizontalLine,  
    HtmlEmbed,  
    GeneralHtmlSupport,  
    HtmlComment,  
    Mention,  
    PageBreak,  
    PasteFromOffice,  
    RemoveFormat,  
    StandardEditingMode,  
    ShowBlocks,  
    Style,  
    SourceEditing,  
    SpecialCharacters,  
    SpecialCharactersEssentials,  
    Table,  
    TableToolbar,  
    TableCellProperties,  
    TableProperties,  
    TableCaption,  
    TableColumnResize,  
    TextTransformation,  
    WordCount,  
    Base64UploadAdapter  
} from 'ckeditor5';  
import {  
    AIAssistant,  
    OpenAITextAdapter,  
    CaseChange,  
    Comments,  
    ExportPdf,  
    ExportWord,  
    MultiLevelList,  
    Pagination,  
    RealTimeCollaborativeComments,  
    RealTimeCollaborativeRevisionHistory,  
    RealTimeCollaborativeTrackChanges,  
    RevisionHistory,  
    TrackChanges,  
    TrackChangesData  
} from 'ckeditor5-premium-features';  
class ClassicEditor extends ClassicEditorBase {}  
class InlineEditor extends InlineEditorBase {}  
class BalloonEditor extends BalloonEditorBase {}  
class DecoupledEditor extends DecoupledEditorBase {}  
for ( const Editor of [ ClassicEditor, InlineEditor, BalloonEditor, DecoupledEditor ] ) {  
    // Plugins to include in the build.  
    Editor.builtinPlugins = [  
        AIAssistant, OpenAITextAdapter,  
        Base64UploadAdapter,  
        Alignment,  
        Autoformat,  
        Bold, Italic, Underline, Strikethrough, Superscript, Subscript, Code,  
        BlockQuote,  
        CKBox, CKBoxImageEdit,  
        CKFinder, CKFinderUploadAdapter,  
        CloudServices,  
        CodeBlock,  
        Comments,  
        Essentials,  
        ExportPdf,  
        ExportWord,  
        Heading,  
        Image, ImageCaption, ImageStyle, ImageToolbar, AutoImage, ImageResize, ImageUpload, ImageInsert, PictureEditing,  
        Indent, IndentBlock,  
        TextPartLanguage,  
        Link, AutoLink, LinkImage,  
        List, ListProperties, TodoList,  
        MultiLevelList,  
        MediaEmbed,  
        Paragraph,  
        FindAndReplace,  
        FontBackgroundColor, FontColor, FontFamily, FontSize,  
        Highlight,  
        HorizontalLine,  
        HtmlEmbed,  
        GeneralHtmlSupport, HtmlComment,  
        Mention,  
        PageBreak,  
        PasteFromOffice,  
        Pagination,  
        RealTimeCollaborativeComments, RealTimeCollaborativeRevisionHistory, RealTimeCollaborativeTrackChanges, PresenceList,  
        RemoveFormat,  
        RevisionHistory,  
        StandardEditingMode,  
        ShowBlocks,  
        Style,  
        SpecialCharacters, SpecialCharactersEssentials,  
        Table, TableToolbar, TableCellProperties, TableProperties, TableCaption, TableColumnResize,  
        TrackChanges, TrackChangesData,  
        TextTransformation,  
        WordCount,  
        DocumentOutline, TableOfContents, FormatPainter, Template, SlashCommand, PasteFromOfficeEnhanced, CaseChange  
    ];  
    Editor.defaultConfig = {  
        toolbar: [  
            'aiCommands', 'aiAssistant',  
            '|',  
            'tableOfContents', 'formatPainter', 'insertTemplate', 'caseChange',  
            '|',  
            'pagination',  
            '|',  
            'trackChanges', 'revisionHistory', 'comment',  
            '|',  
            'heading', 'style',  
            '|',  
            'removeFormat', 'bold', 'italic', 'strikethrough', 'underline', 'code', 'subscript', 'superscript', 'link',  
            '|',  
            'highlight', 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor',  
            '|',  
            'bulletedList', 'numberedList', 'multiLevelList', 'todoList',  
            '|',  
            'blockQuote', 'uploadImage', 'insertTable', 'mediaEmbed', 'codeBlock',  
            '|',  
            'htmlEmbed',  
            '|',  
            'alignment', 'outdent', 'indent',  
            '|',  
            'pageBreak', 'horizontalLine', 'specialCharacters',  
            '|',  
            'textPartLanguage',  
            '|',  
            'showBlocks',  
            '|',  
            'undo', 'redo', 'findAndReplace'  
        ],  
        table: {  
            contentToolbar: [  
                'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties', 'tableCellProperties', 'toggleTableCaption'  
            ]  
        },  
        image: {  
            styles: [  
                'alignCenter',  
                'alignLeft',  
                'alignRight'  
            ],  
            resizeOptions: [  
                {  
                    name: 'resizeImage:original',  
                    label: 'Original size',  
                    value: null  
                },  
                {  
                    name: 'resizeImage:50',  
                    label: '50%',  
                    value: '50'  
                },  
                {  
                    name: 'resizeImage:75',  
                    label: '75%',  
                    value: '75'  
                }  
            ],  
            toolbar: [  
                'imageTextAlternative', 'toggleImageCaption', '|',  
                'imageStyle:inline', 'imageStyle:wrapText', 'imageStyle:breakText', 'imageStyle:side', '|',  
                'resizeImage', '|',  
                'ckboxImageEdit'  
            ],  
            insert: {  
                integrations: [  
                    'insertImageViaUrl'  
                ]  
            }  
        },  
        comments: {  
            editorConfig: {  
                extraPlugins: [ Bold, Italic, Underline, List ]  
            }  
        },  
        root: {  
            placeholder: 'Type the content here!',  
        },  
        language: 'en'  
    };  
    // Enable the `SourceEditing` plugin for ClassicEditor only.  
    if ( Editor === ClassicEditor ) {  
        Editor.builtinPlugins.push( SourceEditing );  
        Editor.defaultConfig.toolbar.push( '|', 'sourceEditing' );  
    }  
    // Enable the `Pagination` plugin for DecoupledEditor only.  
    if ( Editor === DecoupledEditor ) {  
        Editor.builtinPlugins.push( Pagination );  
        Editor.defaultConfig.toolbar.unshift( 'sourceEditing', '|' );  
        Editor.defaultConfig.pagination = {  
            // A4  
            pageWidth: '21cm',  
            pageHeight: '29.7cm',  
            pageMargins: {  
                top: '20mm',  
                bottom: '20mm',  
                right: '12mm',  
                left: '12mm'  
            }  
        };  
    }  
}  
ClassicEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```
4. Unlike when using predefined builds, you are now free to customize the editor by adding or removing plugins. However, before you do this, you should test the editor to make sure it works as expected.

<a id="ckeditor5/latest/updating/nim-migration/predefined-builds.html--cdn-with-global-variables">

##### CDN with global variables

1. Start by removing the `<script>` tags that contain the old build.  
```  
<script src="https://cdn.ckeditor.com/ckeditor5/<VERSION>/classic/ckeditor.js"></script>  
```
2. Add the `<link>` and `<script>` tags to include the editor’s styles and code.

2.1 If you only use the open-source features:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>  
```

2.2 If you also use premium features from our commercial offer:  
```  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />  
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.css" />  
<script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>  
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/48.0.0/ckeditor5-premium-features.umd.js"></script>  
```
3. Replace the old `<script>` tag, which contains the initialization code, depending on the build you are using.  
Classic editor  
Before:  
```  
<script>  
ClassicEditor  
    .create( {  
        attachTo: document.querySelector( '#editor' )  
    } )  
    .catch( error => {  
            console.error( error );  
    } );  
</script>  
```  
After:  
```  
<script>  
const {  
    ClassicEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
class Editor extends ClassicEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Inline editor  
Before:  
```  
<script>  
InlineEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    InlineEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
class Editor extends InlineEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Balloon editor  
Before:  
```  
<script>  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Balloon block editor  
Before:  
```  
<script>  
BalloonEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    BalloonEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    BlockToolbar,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
/*  
Create an additional stylesheet file with the given content:  
.ck.ck-block-toolbar-button {  
    transform: translateX( calc(-1 * var(--ck-spacing-large)) );  
}
*/  
class Editor extends BalloonEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        BlockToolbar,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        blockToolbar: [  
            'undo', 'redo',  
            '|', 'heading',  
            '|', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
            '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
        ],  
        toolbar: {  
            items: [  
                'bold', 'italic', 'link'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Decoupled document editor  
Before:  
```  
<script>  
DecoupledEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    DecoupledEditor,  
    Essentials,  
    Alignment,  
    FontSize,  
    FontFamily,  
    FontColor,  
    FontBackgroundColor,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    Strikethrough,  
    Underline,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageResize,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    IndentBlock,  
    Link,  
    List,  
    ListProperties,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
class Editor extends DecoupledEditor {  
    static builtinPlugins = [  
        Essentials,  
        Alignment,  
        FontSize,  
        FontFamily,  
        FontColor,  
        FontBackgroundColor,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        Strikethrough,  
        Underline,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageResize,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        IndentBlock,  
        Link,  
        List,  
        ListProperties,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',  
                '|', 'bold', 'italic', 'underline', 'strikethrough',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'alignment',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            resizeUnit: 'px',  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:wrapText',  
                'imageStyle:breakText',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        list: {  
            properties: {  
                styles: true,  
                startIndex: true,  
                reversed: true  
            }  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Multi-root editor  
Before:  
```  
<script>  
MultiRootEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    MultiRootEditor,  
    Essentials,  
    CKFinderUploadAdapter,  
    Autoformat,  
    Bold,  
    Italic,  
    BlockQuote,  
    CKBox,  
    CKFinder,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    ImageUpload,  
    PictureEditing,  
    Indent,  
    Link,  
    List,  
    MediaEmbed,  
    Paragraph,  
    PasteFromOffice,  
    Table,  
    TableToolbar,  
    TextTransformation,  
    CloudServices  
} = CKEDITOR;  
class Editor extends MultiRootEditor {  
    static builtinPlugins = [  
        Essentials,  
        CKFinderUploadAdapter,  
        Autoformat,  
        Bold,  
        Italic,  
        BlockQuote,  
        CKBox,  
        CKFinder,  
        CloudServices,  
        Heading,  
        Image,  
        ImageCaption,  
        ImageStyle,  
        ImageToolbar,  
        ImageUpload,  
        Indent,  
        Link,  
        List,  
        MediaEmbed,  
        Paragraph,  
        PasteFromOffice,  
        PictureEditing,  
        Table,  
        TableToolbar,  
        TextTransformation  
    ];  
    static defaultConfig = {  
        toolbar: {  
            items: [  
                'undo', 'redo',  
                '|', 'heading',  
                '|', 'bold', 'italic',  
                '|', 'link', 'uploadImage', 'insertTable', 'blockQuote', 'mediaEmbed',  
                '|', 'bulletedList', 'numberedList', 'outdent', 'indent'  
            ]  
        },  
        image: {  
            toolbar: [  
                'imageStyle:inline',  
                'imageStyle:block',  
                'imageStyle:side',  
                '|',  
                'toggleImageCaption',  
                'imageTextAlternative'  
            ]  
        },  
        table: {  
            contentToolbar: [  
                'tableColumn',  
                'tableRow',  
                'mergeTableCells'  
            ]  
        },  
        language: 'en'  
    };  
}  
Editor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
Superbuild  
Before:  
```  
<script>  
ClassicEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```  
After:  
```  
<script>  
const {  
    ClassicEditor: ClassicEditorBase,  
    InlineEditor: InlineEditorBase,  
    BalloonEditor: BalloonEditorBase,  
    DecoupledEditor: DecoupledEditorBase,  
    CKFinderUploadAdapter,  
    Alignment,  
    Autoformat,  
    Bold,  
    Italic,  
    Underline,  
    Strikethrough,  
    Superscript,  
    Subscript,  
    Code,  
    BlockQuote,  
    CKBox,  
    CKBoxImageEdit,  
    CKFinder,  
    CloudServices,  
    CodeBlock,  
    Essentials,  
    Heading,  
    Image,  
    ImageCaption,  
    ImageStyle,  
    ImageToolbar,  
    AutoImage,  
    ImageResize,  
    ImageUpload,  
    ImageInsert,  
    PictureEditing,  
    Indent,  
    IndentBlock,  
    TextPartLanguage,  
    Link,  
    AutoLink,  
    LinkImage,  
    List,  
    ListProperties,  
    TodoList,  
    MediaEmbed,  
    Paragraph,  
    FindAndReplace,  
    FontBackgroundColor,  
    FontColor,  
    FontFamily,  
    FontSize,  
    Highlight,  
    HorizontalLine,  
    HtmlEmbed,  
    GeneralHtmlSupport,  
    HtmlComment,  
    Mention,  
    PageBreak,  
    PasteFromOffice,  
    RemoveFormat,  
    StandardEditingMode,  
    ShowBlocks,  
    Style,  
    SourceEditing,  
    SpecialCharacters,  
    SpecialCharactersEssentials,  
    Table,  
    TableToolbar,  
    TableCellProperties,  
    TableProperties,  
    TableCaption,  
    TableColumnResize,  
    TextTransformation,  
    WordCount,  
    Base64UploadAdapter  
} = CKEDITOR;  
const {  
    AIAssistant,  
    OpenAITextAdapter,  
    CaseChange,  
    Comments,  
    ExportPdf,  
    ExportWord,  
    MultiLevelList,  
    Pagination,  
    RealTimeCollaborativeComments,  
    RealTimeCollaborativeRevisionHistory,  
    RealTimeCollaborativeTrackChanges,  
    RevisionHistory,  
    TrackChanges,  
    TrackChangesData  
} = CKEDITOR_PREMIUM_FEATURES;  
class ClassicEditor extends ClassicEditorBase {}  
class InlineEditor extends InlineEditorBase {}  
class BalloonEditor extends BalloonEditorBase {}  
class DecoupledEditor extends DecoupledEditorBase {}  
for ( const Editor of [ ClassicEditor, InlineEditor, BalloonEditor, DecoupledEditor ] ) {  
    // Plugins to include in the build.  
    Editor.builtinPlugins = [  
        AIAssistant, OpenAITextAdapter,  
        Base64UploadAdapter,  
        Alignment,  
        Autoformat,  
        Bold, Italic, Underline, Strikethrough, Superscript, Subscript, Code,  
        BlockQuote,  
        CKBox, CKBoxImageEdit,  
        CKFinder, CKFinderUploadAdapter,  
        CloudServices,  
        CodeBlock,  
        Comments,  
        Essentials,  
        ExportPdf,  
        ExportWord,  
        Heading,  
        Image, ImageCaption, ImageStyle, ImageToolbar, AutoImage, ImageResize, ImageUpload, ImageInsert, PictureEditing,  
        Indent, IndentBlock,  
        TextPartLanguage,  
        Link, AutoLink, LinkImage,  
        List, ListProperties, TodoList,  
        MultiLevelList,  
        MediaEmbed,  
        Paragraph,  
        FindAndReplace,  
        FontBackgroundColor, FontColor, FontFamily, FontSize,  
        Highlight,  
        HorizontalLine,  
        HtmlEmbed,  
        GeneralHtmlSupport, HtmlComment,  
        Mention,  
        PageBreak,  
        PasteFromOffice,  
        Pagination,  
        RealTimeCollaborativeComments, RealTimeCollaborativeRevisionHistory, RealTimeCollaborativeTrackChanges, PresenceList,  
        RemoveFormat,  
        RevisionHistory,  
        StandardEditingMode,  
        ShowBlocks,  
        Style,  
        SpecialCharacters, SpecialCharactersEssentials,  
        Table, TableToolbar, TableCellProperties, TableProperties, TableCaption, TableColumnResize,  
        TrackChanges, TrackChangesData,  
        TextTransformation,  
        WordCount,  
        DocumentOutline, TableOfContents, FormatPainter, Template, SlashCommand, PasteFromOfficeEnhanced, CaseChange  
    ];  
    Editor.defaultConfig = {  
        toolbar: [  
            'aiCommands', 'aiAssistant',  
            '|',  
            // Productivity pack.  
            'tableOfContents', 'formatPainter', 'insertTemplate', 'caseChange',  
            '|',  
            'pagination',  
            '|',  
            'trackChanges', 'revisionHistory', 'comment',  
            '|',  
            'heading', 'style',  
            '|',  
            'removeFormat', 'bold', 'italic', 'strikethrough', 'underline', 'code', 'subscript', 'superscript', 'link',  
            '|',  
            'highlight', 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor',  
            '|',  
            'bulletedList', 'numberedList', 'multiLevelList', 'todoList',  
            '|',  
            'blockQuote', 'uploadImage', 'insertTable', 'mediaEmbed', 'codeBlock',  
            '|',  
            'htmlEmbed',  
            '|',  
            'alignment', 'outdent', 'indent',  
            '|',  
            'pageBreak', 'horizontalLine', 'specialCharacters',  
            '|',  
            'textPartLanguage',  
            '|',  
            'showBlocks',  
            '|',  
            'undo', 'redo', 'findAndReplace'  
        ],  
        table: {  
            contentToolbar: [  
                'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties', 'tableCellProperties', 'toggleTableCaption'  
            ]  
        },  
        image: {  
            styles: [  
                'alignCenter',  
                'alignLeft',  
                'alignRight'  
            ],  
            resizeOptions: [  
                {  
                    name: 'resizeImage:original',  
                    label: 'Original size',  
                    value: null  
                },  
                {  
                    name: 'resizeImage:50',  
                    label: '50%',  
                    value: '50'  
                },  
                {  
                    name: 'resizeImage:75',  
                    label: '75%',  
                    value: '75'  
                }  
            ],  
            toolbar: [  
                'imageTextAlternative', 'toggleImageCaption', '|',  
                'imageStyle:inline', 'imageStyle:wrapText', 'imageStyle:breakText', 'imageStyle:side', '|',  
                'resizeImage', '|',  
                'ckboxImageEdit'  
            ],  
            insert: {  
                integrations: [  
                    'insertImageViaUrl'  
                ]  
            }  
        },  
        comments: {  
            editorConfig: {  
                extraPlugins: [ Bold, Italic, Underline, List ]  
            }  
        },  
        root: {  
            placeholder: 'Type the content here!'  
        },  
        language: 'en'  
    };  
    // Enable the `SourceEditing` plugin for ClassicEditor only.  
    if ( Editor === ClassicEditor ) {  
        Editor.builtinPlugins.push( SourceEditing );  
        Editor.defaultConfig.toolbar.push( '|', 'sourceEditing' );  
    }  
    // Enable the `Pagination` plugin for DecoupledEditor only.  
    if ( Editor === DecoupledEditor ) {  
        Editor.builtinPlugins.push( Pagination );  
        Editor.defaultConfig.toolbar.unshift( 'sourceEditing', '|' );  
        Editor.defaultConfig.pagination = {  
            // A4  
            pageWidth: '21cm',  
            pageHeight: '29.7cm',  
            pageMargins: {  
                top: '20mm',  
                bottom: '20mm',  
                right: '12mm',  
                left: '12mm'  
            }  
        };  
    }  
}  
ClassicEditor  
    .create( /* Configuration */ )  
    .catch( error => console.error( error ) );  
</script>  
```
4. Unlike when using predefined builds, you are now free to customize the editor by adding or removing plugins. However, before you do this, you should test the editor to make sure it works as expected.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html">source file: "ckeditor5/latest/updating/technology-upgrades-policy.html"</a>

## Technology upgrades policy

This document describes how CKEditor 5 handles upgrades of its core technologies. The goal is to provide a stable, predictable upgrade path for everyone who builds with CKEditor 5 or contributes to it.

It covers the following technical areas:

* JavaScript and CSS (browser support),
* TypeScript,
* Node.js,
* Framework integrations (Vue, Angular, React).

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--our-primary-goal">

### Our primary goal

Adopt the established best practices of each technology’s community, instead of inventing our own rules. We believe that aligning with well-known standards makes the development process more transparent and easier for plugin authors and for projects that consume CKEditor 5.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--why-this-policy-exists">

### Why this policy exists

This policy will help you:

* Understand when CKEditor 5 introduces breaking changes,
* Prepare your plugins and applications for major upgrades,
* Follow stable patterns instead of learning each change in isolation.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--upgrade-frequency-and-release-cadence">

### Upgrade frequency and release cadence

* CKEditor 5 updates its technology baselines **only in major releases**.
* Minor and patch releases do not introduce breaking changes related to tooling or browser support.
* This predictable cycle lets the developers plan ahead and avoid unexpected breakages.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--what-this-means-for-plugin-authors-and-applications">

### What this means for plugin authors and applications

When you upgrade to a new major version of CKEditor 5:

* Check the updated minimum version of TypeScript,
* If you use our tooling or forked one of our repositories, check the updated minimum version of Node,
* Review browser support changes,
* Update framework integrations to supported versions,
* Follow the corresponding migration guide for detailed instructions.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--detailed-rules">

### Detailed rules

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--impact-matrix">

#### Impact matrix

The table below summarizes how technology-baseline updates affect three key groups: end-users of the editor, projects consuming CKEditor 5, and plugin authors.

| Area                                             | End-users of the editor | Projects consuming CKEditor 5 | Plugin authors |
| ------------------------------------------------ | ----------------------- | ----------------------------- | -------------- |
| **JavaScript and CSS (Browser Support)**         | Yes                     | Yes                           | Yes            |
| **TypeScript**                                   | No                      | Yes                           | Yes            |
| **Node.js**                                      | No                      | No                            | Yes            |
| **Framework integrations (Vue, Angular, React)** | No                      | Yes                           | No             |

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--javascript-and-css-browser-support">

#### JavaScript and CSS (Browser Support)

**Approach:** Once a year, we will update the build target to align with the “Widely available” category defined by the [Baseline web](https://web.dev/baseline) platform standard.

**Reasoning:** Driven by major browser vendors like Google and Mozilla, Baseline provides a clear definition of web features that are mature and safe to use. The “Widely available” category, which we will target, includes features stable across all major browsers for at least 30 months. This approach allows us to balance progress with stability, ensuring CKEditor 5 works for the vast majority of users while leveraging modern web platform features. Its status as a reliable standard is reinforced by growing support from developer tools like [MDN](https://developer.mozilla.org/en-US/blog/baseline-unified-view-stable-web-features/), [caniuse](https://caniuse.com/proxy), [Vite](https://vite.dev/blog/announcing-vite7), [ESLint](https://web.dev/blog/eslint-baseline-integration), and [Angular](https://angular.dev/reference/versions#browser-support).

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--typescript">

#### TypeScript

**Approach:** We will follow the [DefinitelyTyped support window](https://github.com/DefinitelyTyped/DefinitelyTyped?tab=readme-ov-file#support-window). This means the minimum supported TypeScript version will be the oldest version that is less than 2 years old, updated approximately every 6 months.

**Reasoning:** DefinitelyTyped is the de facto standard for TypeScript’ `(@types/... packages)` type definitions in the entire JavaScript ecosystem. Virtually every typed project relies on it, including CKEditor 5\. By mirroring their support policy, we ensure maximum compatibility and interoperability.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--nodejs">

#### Node.js

**Approach:** We will update the development environment to the [latest Active Long-Term Support (LTS) version of Node.js](https://nodejs.org/en/about/previous-releases) approximately every 6 months. We may update more often if Node releases critical security fixes that impact development or CI environments.

**Reasoning:** The Node.js community recommends using either Active LTS or Maintenance LTS for production environments. We chose Active LTS because it provides high stability and security of an LTS release while giving us access to more modern features than versions in the older Maintenance LTS phase.

<a id="ckeditor5/latest/updating/technology-upgrades-policy.html--framework-integrations-vue-angular-react">

#### Framework integrations (Vue, Angular, React)

**Approach:** We will support all officially supported and actively maintained versions of each integration framework. If a library does not publish a clear support window, we will base our decision on usage data, such as community adoption trends and download statistics.

**Reasoning:** Our goal is to ensure that CKEditor 5 integrations are compatible with the versions that most developers use without stretching our resources to maintain legacy frameworks that are no longer relevant or safe. This strikes a balance between stability and staying current with modern development practices.

<a id="ckeditor5/latest/updating/versioning-policy.html">source file: "ckeditor5/latest/updating/versioning-policy.html"</a>

## Versioning policy

CKEditor 5 is a modular ecosystem of over 80 packages, distributed through npm. To provide predictability and a consistent developer experience, we follow a unified versioning and release policy across all packages.

<a id="ckeditor5/latest/updating/versioning-policy.html--package-structure">

### Package structure

CKEditor 5 is delivered in two core packages:

* [**ckeditor5**](https://www.npmjs.com/package/ckeditor5) – the framework and open-source features.
* [**ckeditor5-premium-features**](https://www.npmjs.com/package/ckeditor5-premium-features) – commercial plugins and add-ons.

Together, these aggregate and version over 80 underlying packages that make up the editor framework, features, and utilities.

In addition, the ecosystem provides separately versioned integration packages and tooling:

* **Integrations:** [@ckeditor/ckeditor5-react](https://www.npmjs.com/package/@ckeditor/ckeditor5-react), [@ckeditor/ckeditor5-angular](https://www.npmjs.com/package/@ckeditor/ckeditor5-angular), [@ckeditor/ckeditor5-vue](https://www.npmjs.com/package/@ckeditor/ckeditor5-vue)
* **Tooling:** [ckeditor5-package-generator](https://www.npmjs.com/package/ckeditor5-package-generator), [@ckeditor/ckeditor5-integrations-common](https://www.npmjs.com/package/@ckeditor/ckeditor5-integrations-common)

<a id="ckeditor5/latest/updating/versioning-policy.html--unified-versioning">

### Unified versioning

* All CKEditor 5 packages share the **same version number**.
* This includes both `ckeditor5` and `ckeditor5-premium-features`, as well as all underlying feature and framework packages.
* Integration packages and tooling may follow their own versioning, but major compatibility notes are always documented.

This unified versioning approach is common in large ecosystems (for example, Angular). It simplifies dependency management, avoids mismatched versions, and makes it easy to know which packages are compatible.

<a id="ckeditor5/latest/updating/versioning-policy.html--pinned-dependencies">

### Pinned dependencies

All packages in the ecosystem pin dependencies to specific versions. This prevents issues with npm/yarn/pnpm resolving past versions incorrectly and guarantees reproducible builds.

<a id="ckeditor5/latest/updating/versioning-policy.html--version-numbers">

### Version numbers

We use the **`MAJOR.MINOR.PATCH`** scheme:

* **MAJOR** – Introduced when at least one package requires a **major breaking change**. This affects the entire ecosystem.
* **MINOR** – Introduced when a package adds a new feature or introduces a **minor breaking change**.
* **PATCH** – Introduced when a package only includes bug fixes, internal changes, or documentation updates.

Because CKEditor 5 spans multiple layers – from low-level utilities through framework APIs to ready-to-use builds – our approach differs from strict [Semantic Versioning](https://semver.org/). Instead, our policy balances stability with the flexibility needed for such a broad ecosystem.

<a id="ckeditor5/latest/updating/versioning-policy.html--breaking-changes">

### Breaking changes

Breaking changes are categorized based on which layer of the ecosystem they affect:

* **Integration layer** (editor builds, configuration, and top-level APIs):  
  * Breaking changes are considered **major**.
  * Introduced very rarely and only when unavoidable.
* **Plugin development API** (packages such as `@ckeditor/ckeditor5-engine` or `@ckeditor/ckeditor5-core`):  
  * Breaking changes are also considered **major**.
  * Introduced occasionally, but batched to reduce the number of major releases.
* **Low-level customization APIs and feature customization APIs** (internal utilities, hooks, helper functions, and lower-level APIs exposed by specific features, for example the Link balloon):  
  * Designed mainly for **deep customizations of existing features**, rather than for building integrations or plugins.
  * Treated as **less stable** – breaking changes are considered **minor** and may occur more often as these APIs evolve with feature development.
  * Provide powerful flexibility but are closer to implementation details, so they should not be relied upon for long-term compatibility guarantees.

<a id="ckeditor5/latest/updating/versioning-policy.html--release-schedule">

### Release schedule

We typically publish a **new major release of CKEditor 5 every 6 months**, though in some cases new majors may arrive sooner. Each new major replaces the previous one as the actively supported version, ensuring that all users benefit from the latest improvements, fixes, and compatibility updates.

For projects that need **long-term stability**, we also offer the commercial **CKEditor 5 LTS (Long-term Support) Edition**. Every two years, one major release (starting with **v47.0.0**) is designated as an LTS release, providing up to **3 years of guaranteed updates** – 6 months of active development followed by 2.5 years of maintenance with security and critical compatibility fixes. Read more in the [CKEditor 5 LTS Edition](#ckeditor5/latest/getting-started/setup/using-lts-edition.html) guide.

<a id="ckeditor5/latest/updating/versioning-policy.html--release-channels">

### Release channels

CKEditor 5 is distributed through several release channels, each serving a different purpose:

* **Stable releases**: The recommended versions for production use. These are fully tested and supported, and are available via **npm**, **ZIP packages**, and the **official CDN**.
* **Alpha builds**: Used for early access and testing before a stable release. Alpha builds are published to npm under the `alpha` dist-tag.
* **Nightly builds**: Generated automatically from the latest development branch. They are available via npm under the `nightly` dist-tag and are intended for testing the newest changes.

If you encounter an issue, please [report it in the CKEditor 5 issue tracker](https://github.com/ckeditor/ckeditor5/issues). Early feedback (especially about alpha and nightly releases) gives us more time to investigate and resolve problems before they reach a stable release.

<a id="ckeditor5/latest/updating/versioning-policy.html--tracking-changes">

### Tracking changes

To stay up to date with changes:

* **Changelog**: Check the [CKEditor 5 changelog](https://github.com/ckeditor/ckeditor5/blob/stable/CHANGELOG.md).
* **News**: Read the [CKEditor Ecosystem Blog](https://ckeditor.com/blog/) or subscribe to the [newsletter](http://ckeditor.com/#newsletter-signup).
* **npm**: Follow the [ckeditor5](https://www.npmjs.com/package/ckeditor5) and [ckeditor5-premium-features](https://www.npmjs.com/package/ckeditor5-premium-features) packages.

<a id="ckeditor5/latest/updating/versioning-policy.html--update-guides">

### Update guides

When a release introduces breaking or otherwise important changes, the [Updating CKEditor 5](#ckeditor5/latest/updating/index.html) section provides technical details and migration steps. Always review these guides after a release to keep your integration stable.

# Cloud Services

<a id="cs/latest/developer-resources/apis/authentication.html">source file: "cs/latest/developer-resources/apis/authentication.html"</a>

## Authentication

<a id="cs/latest/developer-resources/apis/authentication.html--ckeditor-cloud-services-rest-api">

### CKEditor Cloud Services REST API

The REST API uses HMAC Authentication. It means that every request must include a signature and a timestamp.  
The signature needs to be created in accordance with the requirements mentioned in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide.

<a id="cs/latest/developer-resources/apis/authentication.html--examples">

#### Examples

Detailed examples for Node.js and other programming languages can be found in the [Request Signatures examples](#cs/latest/examples/security/request-signature-nodejs.html) section.

<a id="cs/latest/developer-resources/apis/authentication.html--converters-apis">

### Converters APIs

Converters APIs use JWT to authenticate requests. The generated token should be placed as `Authorization` header.

<a id="cs/latest/developer-resources/apis/authentication.html--example">

#### Example

The token should be generated based on the example below:

```
    const jwt = require( 'jsonwebtoken' );

    const accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';
    const environmentId = 'LJRQ1bju55p6a47RwadH';

    const payload = {
        aud: environmentId
    };

    const token = jwt.sign( payload, accessKey, { algorithm: 'HS256', expiresIn: '24h' } );

    console.log( 'Authentication token', token );

```

Please keep in mind that token generation should be done on a backend side, to avoid exposing `accessKey` to public.  
Anyone who gets the `accessKey` is able to use converters using your subscription.

More detailed examples for Node.js and for other programming language can be found in a [Token endpoints examples](#cs/latest/examples/token-endpoints/nodejs.html) section.

<a id="cs/latest/developer-resources/apis/authentication.html--next-steps">

### Next steps

Read more about the overall [System security](#cs/latest/guides/system-security.html).

<a id="cs/latest/developer-resources/apis/errors.html">source file: "cs/latest/developer-resources/apis/errors.html"</a>

## Errors

The CKEditor Collaboration Server REST API uses standard HTTP response codes.

<a id="cs/latest/developer-resources/apis/errors.html--error-body">

### Error body

Each error has the following fields:

* `message` – It contains a short error description.
* `status_code` – It contains the response status.
* `trace_id` – It is a unique request identifier.
* `data` – It may contain various information and may have various structure depending on the endpoint.
* `explanation` – It contains an explanation why the particular error ocurred.
* `action` – In case some action can solve the problem it contains a description of what should be done.

<a id="cs/latest/developer-resources/apis/errors.html--example">

### Example

The presented error is an example which can occur while importing comments to a given document, but comments were already imported.

```
{
  "message": "The target document already contains an import of the comments but it is based on a different snapshot.",
  "traceId": "e5abd738-db35-4372-b1de-cff9b48cc311",
  "statusCode": 409,
  "explanation": "A single target document cannot contain multiple imports of the same source.",
  "action": "Use a different target document ID.",
  "data": {
    "documentId": "doc-1",
    "importSnapshotAt": "2022-10-19T11:12:21.357Z"
  }
}

```

<a id="cs/latest/developer-resources/apis/overview.html">source file: "cs/latest/developer-resources/apis/overview.html"</a>

## RESTful APIs - overview

CKEditor Cloud Services offer several REST APIs that can be used for server integration.

The APIs currently include:

* **CKEditor Cloud Services Restful APIs** – Provides a full-featured RESTful API that you can use to create a server-to-server integration.
* **CKBox Restful API** – Provides an API for managing data stored in the CKBox.
* **HTML to PDF Converter API** – Provides an API for converting HTML/CSS documents to PDF format.
* **HTML to DOCX Converter API** – Provides an API for converting HTML documents to Microsoft Word `.docx` files.
* **DOCX to HTML Converter API** – Provides an API for converting Microsoft Word `.docx`/`.dotx` files to HTML documents.

<a id="cs/latest/developer-resources/apis/overview.html--usage">

### Usage

Each method can be used for different purposes. For example, the REST API methods for comments allow for synchronizing comments between CKEditor Cloud Services and another system. In addition to that, CKEditor Cloud Services can be used as a database for comments because it is possible to download them via the REST API at the time they are being displayed.

An example of using another API method is getting the content of the document from a collaborative editing session. This feature can be used to build an auto-save mechanism for the document, which should reduce transfer costs — auto-save requests are not executed by each connected user but only by the system once at a time.

<a id="cs/latest/developer-resources/apis/overview.html--information">

### Information

CKEditor Cloud Services REST APIs provide a lot of powerful methods that make it possible to control and manage data.

<a id="cs/latest/developer-resources/apis/overview.html--documentation">

### Documentation

<a id="cs/latest/developer-resources/apis/overview.html--ckeditor-cloud-services-restful-apis">

#### CKEditor Cloud Services Restful APIs

The API documentation is available here: <https://help.cke-cs.com/api/docs/>. It is an aggregator of all Restful APIs currently available.

<a id="cs/latest/developer-resources/apis/overview.html--ckbox-restful-api">

#### CKBox Restful API

The API documentation is available at <https://api.ckbox.io/api/docs>.

Read more about this service in the [CKBox](#ckbox/latest/guides/index.html) guide.

<a id="cs/latest/developer-resources/apis/overview.html--html-to-pdf-converter-api">

#### HTML to PDF Converter API

The API documentation is available at <https://pdf-converter.cke-cs.com/docs>.

Read more about this service in the [Export to PDF](#cs/latest/guides/export-to-pdf/overview.html) guide.

<a id="cs/latest/developer-resources/apis/overview.html--html-to-docx-converter-api">

#### HTML to DOCX Converter API

The API documentation is available at <https://docx-converter.cke-cs.com/docs#section/Export-to-Word>.

Read more about this service in the [Export to Word](#cs/latest/guides/export-to-word/overview.html) guide.

<a id="cs/latest/developer-resources/apis/overview.html--docx-to-html-converter-api">

#### DOCX to HTML Converter API

The API documentation is available at <https://docx-converter.cke-cs.com/docs#section/Import-from-Word>.

Read more about this service in the [Import from Word](#cs/latest/guides/import-from-word/overview.html) guide.

<a id="cs/latest/developer-resources/easy-image/service-details.html">source file: "cs/latest/developer-resources/easy-image/service-details.html"</a>

## Easy Image

This article explains how Easy Image works internally and is geared towards more advanced users.

<a id="cs/latest/developer-resources/easy-image/service-details.html--image-processing">

### Image processing

For every uploaded image, Easy Image produces several optimized versions of the same image.

Image sizes are calculated in two ways depending on the width of the original image:

* For large images (wider than 800px) the width is reduced every 10%.
* For small images the width is reduced every 80px until the 100px limit is reached.

The original image gets saved in the cloud, too.

Thanks to offering several versions of the same image, devices with smaller resolutions, such as mobile devices, may request images that fit their display, reducing the bandwidth and improving the loading time of a website.

<a id="cs/latest/developer-resources/easy-image/service-details.html--examples">

#### Examples

For a 4000px wide image the following versions of it will be created: 400px, 800px, 1200px, 1600px, 2000px, 2400px, 2800px, 3200px, 3600px and 4000px.

For a 500px wide image the following versions will be created: 100px, 180px, 260px, 340px, 420px and 500px.

<a id="cs/latest/developer-resources/easy-image/service-details.html--upload-response">

### Upload response

The Easy Image service responds with a JSON object containing addresses of generated versions of the image. The keys indicate the width of the image, the original image is named `default`. By default the aspect ratio is preserved.

<a id="cs/latest/developer-resources/easy-image/service-details.html--sample-response">

#### Sample response

```
{
   "390":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_390",
   "780":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_780",
   "1170":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1170",
   "1560":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1560",
   "1950":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1950",
   "2340":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_2340",
   "2730":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_2730",
   "3120":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3120",
   "3510":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3510",
   "3840":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3840",
   "default":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg"
}

```

The entire communication is hidden from the developer and requires no effort on their part.

<a id="cs/latest/developer-resources/easy-image/service-details.html--generated-html-markup">

#### Generated HTML markup

The markup used for images varies a bit depending on the editor version, however, the `<img>` element always contains a similar [srcset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-srcset) attribute where all the generated versions of the image are listed:

```
<figure ...>
    <figcaption ...>...</figcaption>
    <img alt="..." src="https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg" width="3840"
    srcset="https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_390 390w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_780 780w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1170 1170w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1560 1560w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1950 1950w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_2340 2340w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_2730 2730w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3120 3120w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3510 3510w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3840 3840w" sizes="100vw">
</figure>

```

You can find more information about `srcset` and responsive images in the [Responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia%5Fand%5Fembedding/Responsive%5Fimages) article on MDN.

<a id="cs/latest/developer-resources/easy-image/service-details.html--requesting-a-different-size-of-the-image">

### Requesting a different size of the image

The Easy Image service supports requesting any size of an image.

<a id="cs/latest/developer-resources/easy-image/service-details.html--parameters">

#### Parameters

To request an image with a custom size, add parameters to the default URL. Parameters are separated by commas. The names of parameters and values should be separated by an underscore, for example `w_300,h_100`.

Abbreviated names of parameters must be used, see the table below:

| Abbreviated name | Full name |
| ---------------- | --------- |
| w                | width     |
| h                | height    |

When `w` and `h` are used together, aspect ratio is ignored and a stretched image will be returned.

<a id="cs/latest/developer-resources/easy-image/service-details.html--example">

##### Example

A sample default image URL:  
`https://cdn.cke-cs.com/aX1FymZU/images/48f57_image1.jpg`

The same image resized to 200x100px:  
`https://cdn.cke-cs.com/aX1FymZU/images/48f57_image1.jpg/w_200,h_100`

<a id="cs/latest/developer-resources/easy-image/service-details.html--supported-file-formats">

### Supported file formats

Easy Image supports the following formats:

* `png`
* `jpeg`
* `bmp` (images in `bmp` will be converted to `png`)
* `tiff`
* `webp`
* `gif` (animated gifs are also supported)

<a id="cs/latest/developer-resources/easy-image/service-details.html--roles-for-easy-image">

### Roles for Easy Image

There is no need to specify any roles for Easy Image, because they are assigned to the environment. It means that each user that belongs to the environment is allowed to upload images. After the upload, images are public and can be downloaded without any restrictions.

<a id="cs/latest/developer-resources/easy-image/service-details.html--integration-with-ckeditor-5">

### Integration with CKEditor 5

<a id="cs/latest/developer-resources/easy-image/service-details.html--installation">

#### Installation

This package is part of our open-source aggregate package. Just install CKEditor 5 to gain access to it.

```
npm install ckeditor5

```

Then add Easy Image to your plugin list and configure the feature. For instance:

```
import { EasyImage, Image } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ EasyImage, Image, /* ... */ ],
        toolbar: [ 'uploadImage', /* ... */ ],

        // Configure the endpoint. See the "Configuration" section above.
        cloudServices: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

```

To make enabling image upload in CKEditor 5 a breeze, the `EasyImage` plugin integrates with the Easy Image service provided by CKEditor Cloud Services. Enabling it is straightforward and the results are immediate. Simply configure CKEditor 5 setting shown above, putting in correct upload URL and Token Endpoint.

<a id="cs/latest/developer-resources/easy-image/service-details.html--configuring-allowed-file-types">

#### Configuring allowed file types

The allowed file types that can be uploaded should actually be configured in two places:

* On the client side, in CKEditor 5, restricting image upload through the CKEditor 5 UI and commands.
* On the server side, in Easy Image, restricting the file formats that are accepted in Easy Image (as explained above).

<a id="cs/latest/developer-resources/easy-image/service-details.html--client-side-configuration">

##### Client-side configuration

Use the `image.upload.types` configuration option to define the allowed image MIME types that can be uploaded to CKEditor 5.

By default, users are allowed to upload `jpeg`, `png`, `gif`, `bmp`, `webp` and `tiff` files. This corresponds with file formats supported by Easy Image, but you can modify the list to limit the number of allowed image types.

<a id="cs/latest/developer-resources/environments/environments-management.html">source file: "cs/latest/developer-resources/environments/environments-management.html"</a>

## Environments management

You need to create an environment first to work with CKEditor Cloud Services. Environments allow you to create access credentials, manage webhooks, configure features, and connect to CKEditor Cloud Services.

<a id="cs/latest/developer-resources/environments/environments-management.html--managing-environments">

### Managing environments

In order to manage your environments, you should log in to the [Customer Portal](https://portal.ckeditor.com) for SaaS or to the Management Panel for On-Premises.

The “Overwiev” section lists your active product subscriptions. Select the “Cloud environments” link to manage your environments.

<a id="cs/latest/developer-resources/environments/environments-management.html--creating-a-new-environment">

#### Creating a new environment

To create a new environment, click the “Create environment” button.

A modal will show up asking for the name of the new environment. Provide the name and click the “Create environment” button.

The newly created environment will show up on the list of environments.

<a id="cs/latest/developer-resources/environments/environments-management.html--removing-an-environment">

#### Removing an environment

From the list of environments select the one that you want to remove and click the “Remove” button in the “Actions” column.

The modal will show up and will prompt for a confirmation of the environment deletion. Confirm by clicking the “Remove” button.

<a id="cs/latest/developer-resources/environments/environments-management.html--cloud-region">

#### Cloud region

<a id="cs/latest/developer-resources/environments/environments-management.html--with-custom-plan-and-multi-region">

##### With Custom plan and multi-region

If you have a [Custom plan](https://ckeditor.com/pricing/) with the multi-region addon, you can have multiple environments created in both regions.

You can choose environment region during environment creation.

<a id="cs/latest/developer-resources/environments/environments-management.html--without-multi-region">

##### Without multi-region

Without multi-region, all environments are created within the same region. Changing a region of an existing environment is not possible on user level, please [contact support](https://ckeditor.com/contact/).

To change a region, you need to delete all environments in the old region first. Only then you can change the region and create new environments in this new region.

<a id="cs/latest/developer-resources/environments/environments-multitenancy.html">source file: "cs/latest/developer-resources/environments/environments-multitenancy.html"</a>

## Environments multitenancy

CKEditor Cloud Services guarantee a logical separation between different environments. All secrets and keys are unique for each environment, which minimizes the chance of requesting a different environment than intended.

Each environment uses separate secrets to encrypt its data in the database.

You can create as many environments as you need. Removing data from one environment does not affect the state of the others.

<a id="cs/latest/developer-resources/environments/overview.html">source file: "cs/latest/developer-resources/environments/overview.html"</a>

## Environments overview

**An environment** is a logical structure that separates data in the CKEditor Cloud Services ecosystem.  
A single product can contain many environments. It allows for creation of independent spaces on the Collaboration Server and other services.

<a id="cs/latest/developer-resources/environments/overview.html--security">

### Security

Each environment has its own set of `accessKeys` and `apiSecret`. It means that for every environment the token endpoint and the request signature script need to be separate. It reduces the risk of connecting unintentionally to other environments.

Data belonging to the environment is encrypted by using different encryption keys for each environment.

You can learn more about security in [System Security](#cs/latest/guides/system-security.html) guide.

<a id="cs/latest/developer-resources/environments/overview.html--cloud-region">

### Cloud region

Each environment has a [cloud region](#cs/latest/guides/saas-vs-on-premises.html--cloud-region). The region is set per-subscribtion and (unless you have Custom plan with multi-region) cannot be changed for existing environments by the user. This topic is addressed in more detail in the [Environment management](#cs/latest/developer-resources/environments/environments-management.html--cloud-region) guide.

<a id="cs/latest/developer-resources/environments/overview.html--next-steps">

### Next steps

* [Create a new environment](#cs/latest/developer-resources/environments/environments-management.html--creating-a-new-environment)

<a id="cs/latest/developer-resources/index.html">source file: "cs/latest/developer-resources/index.html"</a>

## Cloud Services - Developer resources

CKEditor Cloud Services allows to manage documents and related data by using server-server communication. It can be done in both directions.

The Collaboration Server is able to communicate any other application by sending HTTP request in case of event occurrence by Webhooks.

The other applications can manipulate the Collaboration Server data by using the REST API.

Refer to the following sections for more information:

* [Overview](#cs/latest/developer-resources/overview.html) – An introduction to Cloud Services developer resources.
* [Restful APIs](#cs/latest/developer-resources/apis/overview.html) – Instructions on how to utilize the **REST API**.
* [Server-side Editor API](#cs/latest/developer-resources/server-side-editor-api/editor-scripts.html) – Instructions on how to utilize the **Server-side Editor API**.
* [Webhooks](#cs/latest/developer-resources/webhooks/overview.html) – Instructions on how to use the **Webhooks** mechanism.
* [API Secret](#cs/latest/developer-resources/security/api-secret.html) – Instructions on how to access and use **API Secret**.
* [Request Signature](#cs/latest/developer-resources/security/request-signature.html) – Instructions on how to generate **Request Signature** to authenticate requests and events.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html">source file: "cs/latest/developer-resources/monitoring/insights-panel.html"</a>

## Insights panel

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--insights-panel-overview">

### Insights Panel overview

The Insights Panel feature allows to gather, list, and filter business (audit) logs that come from the server. These logs provide a good insight into what is going on internally in your environments. Also, the Insights Panel serves as a useful debugging tool, especially during integration.

Using the Insights Panel feature, you can check logs for the CKEditor Collaboration Services, CKBox, Import/Export to Word, and Export to PDF.  
For Import/Export to Word and for Export to PDF, the Insights Panel feature is available only for the SaaS variant.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--activating-insights-feature">

### Activating Insights feature

By default, the Insights feature is turned off for all environments.

To activate the Insights feature:

1. Log in to the [Cloud Services Portal](https://portal.ckeditor.com/) (Management Panel when using On-Premises). Go to the `Feature configuration` section of the `Cloud environments` tab for the selected environment. Note that the feature is activated separately for every environment.
2. Under the `INSIGHTS` section, switch on the `Business logs` toggle.
1. After turning on the toggle, the CS server will start collecting business and details logs for that environment from now on.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--listing-logs">

### Listing logs

To list the collected logs, go to the `Insights Panel` tab in the Cloud Services Portal (or the Management Panel if using On-Premises). By default, the log list displays business and details logs from the last 2 hours. To change the time range, use the date picker to set the desired filtering range.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--filtering-logs">

### Filtering logs

To search the logs, use the filters to narrow down the desired results.

The currently available filters are:

* `Trace ID` – filtering by `traceId`.
* `User ID` – filtering by `userId`,
* `Error level` – filtering by `warn`, `fail` and `error` levels,
* `Document ID` – filtering by `documentId` – only for the CKEditor Collaboration Services,
* `Asset ID` – filtering by `assetId` – only for the CKBox,
* `Category ID` – filtering by `categoryId` – only for the CKBox,

Filters can be combined with one another.

You can paste the filter value into the filter box (useful for searching by `trace`). It is also possible to choose one of the suggested values - these are aggregated from the logs matching your queries.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--log-structure">

#### Log structure

Here are the key fields included in a log:

* `msg` \- A detailed log message.
* `traceId` \- A unique RPC call ID.
* `data` \- An object containing additional information. It may vary between different logs.
* `time` \- An occurrence date.
* `tags` \- Tags associated with the log. The possible tags are `business` (information about the main action initiated by the user or an API) or `details` (detailed information about the main action or information about additional events that have been triggered by the main action).

An example log:

```
{
    "msg": "The user authenticated to the server (userId: xhb1jjs10uq8un9wt0vc)",
    "traceId": "b36f1967-7778-4c0d-97a2-37caba24d59e",
    "data": {
      "socketId": "vem71503nieel8ewoxjb",
      "environmentId": "ciy6g1w4y1a6qm146our",
      "userId": "xhb1jjs10uq8un9wt0vc"
    },
    "time": "2022-04-25T09:53:01.257Z",
    "tags": "business"
}

```

Log stream records are grouped together and can contain both `business` and `details` logs linked together by `traceId`. Log details are available after clicking on the log record.

<a id="cs/latest/developer-resources/monitoring/insights-panel.html--log-retention">

### Log retention

All logs older than 31 days are periodically removed from the environment for the SaaS variant.  
For the On-Premises variant, the logs are retained for 14 days.

This is done automatically and doesn’t require additional configuration.

<a id="cs/latest/developer-resources/overview.html">source file: "cs/latest/developer-resources/overview.html"</a>

## Developer resources overview

<a id="cs/latest/developer-resources/overview.html--communication-with-the-ckeditor-cloud-services">

### Communication with the CKEditor Cloud Services

CKEditor Cloud Services provides multiple ways of communication with the application it cooperates with. Cloud Services can communicate with both fronted and backend part of the application.

To communicate with the browser part, it most often utilizes the CKEditor 5 plugins, which only need to pass required configuration properties to work.

Another type of communication is the **server to server communication**. The CKEditor Cloud Services provides a variety of REST APIs to communicate with. In many cases the event-based communication, through webhooks, can improve overall performance of the integration. The CKEditor Cloud Services provides many webhook events, which can be used to optimize the workflow of the application.

By using a combination of webhooks and REST APIs you can create a reliable and efficient integration with the CKEditor Collaboration Server. REST APIs allow to import, export and manage data stored on the CKEditor Collaboration Server. The Webhooks inform the integrated application about events that ocurr in the documents and editing sessions.

<a id="cs/latest/developer-resources/security/access-key.html">source file: "cs/latest/developer-resources/security/access-key.html"</a>

## Access key

<a id="cs/latest/developer-resources/security/access-key.html--access-credentials-overview">

### Access credentials overview

The Access key is used for generating a token which can be used to connect to the CKEditor Collaboration Server and other services.

Single environment can use many access keys in a same time.

<a id="cs/latest/developer-resources/security/access-key.html--rotating-access-credentials">

### Rotating access credentials

It is recommended to periodically change the access credentials. It can be done by creating a new one and updating its value in the application where the token is generated.

After ensuring that an updated key is available for all users, the old access key can be removed. Please note that old tokens can still be in use for short period of time, so it is recommended to give users some time to update. The update of access credentials is unnoticeable for collaborating users. Instructions on how to create and delete the access key can be found below.

<a id="cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials">

### Managing the access credentials

The access credentials are available for every environment in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises. You can manage them by following the steps below:

<a id="cs/latest/developer-resources/security/access-key.html--creating-access-credentials">

#### Creating access credentials

From the list of environments select the one that you want to manage.

Go to the “Access credentials” tab and click the “Create a new access key” button.

The modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

For your safety, the access key value will disappear in a few seconds. You will be able to display it again by clicking the “Show” button. Make sure to keep the access credentials in a safe place.

<a id="cs/latest/developer-resources/security/access-key.html--removing-the-access-credentials">

#### Removing the access credentials

From the list of access keys, select the one that you want to remove and click the red “Remove” link in the “Actions” column.

The modal will show up and will prompt for a confirmation of the access key removal. Confirm by clicking the “Remove” button.

<a id="cs/latest/developer-resources/security/api-secret.html">source file: "cs/latest/developer-resources/security/api-secret.html"</a>

## API secret

<a id="cs/latest/developer-resources/security/api-secret.html--api-secret-overview">

### API secret overview

The API secret is used for authentication in the most critical parts of the system where access should be limited. For example, the API secret is used in REST APIs and webhooks mechanisms.

<a id="cs/latest/developer-resources/security/api-secret.html--api-secrets-management">

### API secrets management

It is possible to create up to 3 API secrets, by using the “API secrets” tab in the [Customer Portal](https://portal.ckeditor.com/). It allows for an easier API secret rotation. The “API secrets” tab also provides information such as the creation and last usage dates of a given API secret.

<a id="cs/latest/developer-resources/security/api-secret.html--create-a-new-api-secret">

#### Create a new API secret

To generate a new API secret click the “Create a new API secret” visible on the “API secrets” tab.

The API secret’s value will be shown only once. Copy the newly created API secret and save it in a safe place.  
It will not be possible to display the full value of this API secret again.

<a id="cs/latest/developer-resources/security/api-secret.html--set-api-secret-to-be-used-to-sign-webhooks-requests">

##### Set API secret to be used to sign webhooks requests

The first API secret created in the “API secrets” tab will be automatically set for signing webhooks requests.

To change which API secret should be used for that, click the “Use with webhooks” button of the given API secret in the “Actions” column.

The change must be confirmed or canceled.

<a id="cs/latest/developer-resources/security/api-secret.html--remove-api-secret">

#### Remove API secret

To remove the API secret click the red “Trash” icon with the “Remove” prompt in the “Actions” column next to the API secret you want to remove.  
This operation cannot be undone, so it requires confirmation by writing the supplied phrase in a confirmation modal and clicking the “Confirm” button.

<a id="cs/latest/developer-resources/security/request-signature.html">source file: "cs/latest/developer-resources/security/request-signature.html"</a>

## Request signature

<a id="cs/latest/developer-resources/security/request-signature.html--request-signature-overview">

### Request signature overview

The safest solution is to only use communication over HTTPS, but there may be cases when HTTPS communication between the system and CKEditor Cloud Services is not possible, and only HTTP communication can be used. Therefore, to secure both situations, CKEditor Cloud Services uses the HMAC algorithm to secure the connections between systems.

<a id="cs/latest/developer-resources/security/request-signature.html--algorithm">

### Algorithm

Each request sent from or received by CKEditor Cloud Services should have the following headers:

* `X-CS-Timestamp`
* `X-CS-Signature`

The signature is generated using the SHA-256 algorithm using one of [API secrets](#cs/latest/developer-resources/security/api-secret.html) as a secret and based on the following data:

* HTTP method – `GET`, `POST`, `PUT`, `DELETE`.
* URL – The path of the URL.  
For `https://docs.cke-cs.com/api/v5/docs?page=1` this is just `/api/v5/docs?page=1`.
* timestamp – The same value as in the `X-CS-Timestamp` header.
* body – A string from the body for `POST` and `PUT` or an empty string for other methods.

The above data should be combined into one string in the following way:

* Convert the HTTP method name to an upper case string.
* Add the URL (path name).
* Add the timestamp.
* Add the body converted to a string.

<a id="cs/latest/developer-resources/security/request-signature.html--examples">

### Examples

Check an [example of a request signature implementation in Node.js](#cs/latest/examples/security/request-signature-nodejs.html).  
Check an [example of a request signature implementation in ASP.NET](#cs/latest/examples/security/request-signature-dotnet.html).  
Check an [example of a request signature implementation in Java](#cs/latest/examples/security/request-signature-java.html).  
Check an [example of a request signature implementation in PHP](#cs/latest/examples/security/request-signature-php.html).  
Check an [example of a request signature implementation in Python 3](#cs/latest/examples/security/request-signature-python.html).

<a id="cs/latest/developer-resources/security/roles.html">source file: "cs/latest/developer-resources/security/roles.html"</a>

## Roles and permissions

<a id="cs/latest/developer-resources/security/roles.html--roles-and-permissions-overview">

### Roles and permissions overview

Because CKEditor Cloud Services authenticates users and verifies their identity, information to which parts the user has access must be provided. For this purpose, CKEditor Cloud Services uses [tokens](#cs/latest/developer-resources/security/token-endpoint.html) and a permissions mechanism.

In order to simplify and facilitate providing information about permissions, CKEditor Cloud Services uses roles. Roles contain a set of permissions describing the actions that the user can and cannot do. For a more fine-grained access control, it is possible to define permissions and use these instead of roles. It is also possible to use both roles and permissions to create a custom access solution.

<a id="cs/latest/developer-resources/security/roles.html--roles-for-export-to-pdf-and-export-to-word">

### Roles for Export to PDF and Export to Word

There is no need to specify any roles for the PDF and Word converters. Each user that belongs to the environment with enabled converters is allowed to use them.

<a id="cs/latest/developer-resources/security/roles.html--roles-for-collaboration">

### Roles for Collaboration

The user is authorized only to documents listed in `auth.collaboration` and may have a different role in each document.

```
{
    "auth": {
        "collaboration": {
            "doc-1": {
                "role": "reader"
            },
            "doc-2": {
                "role": "commentator"
            },
            "doc-2": {
                "role": "writer"
            }
        }
    }
}

```

The list of documents to which the user is authorized should be specified by providing their IDs or [patterns](#cs/latest/developer-resources/security/roles.html--patterns) (if the user has access to a group of documents).

<a id="cs/latest/developer-resources/security/roles.html--roles">

#### Roles

Each role contains a set of permissions describing the actions that the user can and cannot do.

CKEditor Cloud Services provides the following 3 roles:

* `reader` – A user with this role has read-only access to the document. It means that the user is NOT authorized to make any changes to the document (this includes adding comments). This role includes the following permission types: `document:read`, `comment:read`.
* `commentator` – A user with this role has read-only access to the document but is authorized to comment. It means that the user is NOT allowed to modify the content of the document but is allowed to leave comments. This role includes the following permission types: `document:read`, `comment:read`, `comment:write`, and allows to perform the following actions:  
  * creating new comment threads,
  * removing own comment threads,
  * adding comments to all existing comment threads,
  * removing and modifying own comments from all existing comment threads,
  * resolving and reopening any comment threads (in the comments archive).
* `writer` – A user with this role has full access to the document. It means that the user is authorized to make any changes to the document (including adding comments). This role includes the following permission types: `document:read`, `document:write`, `comment:read`, `comment:write`, `comment:admin`, and allows to perform the following actions:  
  * creating new comment threads,
  * removing all comment threads,
  * adding comments to all existing comment threads,
  * removing and modifying own comments from all existing comment threads,
  * resolving and reopening any comment threads (in the comments archive).

**Please note:** None of the above roles allows removing or modifying single comments created by other users. To acquire such a privilege, please include the `comment:modify_all` permission.

<a id="cs/latest/developer-resources/security/roles.html--permissions">

#### Permissions

For more fine-grained access control, CKSource Cloud Services uses permissions instead of predefined roles. This feature is available since CKEditor 5 v29.0.0.

CKEditor Cloud Services provides five permission types:

* `document:read` – A user with this permission type has read-only access to the document. It means that the user is NOT authorized to make any changes to the document (including no ability to comment).
* `document:write` – A user with this permission type is authorized to modify the content of the document. This permission also allows the user to implicitly resolve any comment thread in the comments archive by removing content with a comment thread marker. What is more, it allows to implicitly reopen any comment thread by performing the undo operation.
* `comment:read` – A user with this permission type has read-only access to the document’s comments. It means that the user is NOT authorized to add new comments or edit the existing ones.
* `comment:write` – A user with this permission type is authorized to add new comments, edit, and remove their own comments and comment threads. Moreover, it allows to resolve and reopen any comment thread in the comment archive.
* `comment:admin` – A user with this permission type can remove comment threads added by any user. However, this permission does not allow removing or modifying single replies authored by others. To take advantage of this permission, users must have also the `comment:write` permission.
* `comment:modify_all` – A user with this permission type can remove or modify comments added by other users. However, this permission does not allow removing whole comment threads authored by others.

```
{
    "auth": {
        "collaboration": {
            "*": {
                "permissions": [
                    "document:read",
                    "document:write",
                    "comment:read"
                ]
            }
        }
    }
}

```

The described permissions authorize the user only for the actions described. For example, the `document:write` permission, which authorizes the user to modify the content of the document, does not include the `document:read` permission. It means, that the `document:read` permission should be included in the permissions list as well, to authorize the user to read the document. The `comment:admin` permission is no exception to this rule.

<a id="cs/latest/developer-resources/security/roles.html--mixing-roles-and-permissions">

#### Mixing roles and permissions

In some cases, it would be handy to mix predefined roles with permissions.

Example: The following sample defines a user that has the `commentator` role in all documents and additionally, the user has the `comment:admin` permission which allows for removing comment threads added by other users.

```
{
    "auth": {
        "collaboration": {
            "*": {
                "role": "commentator",
                "permissions": [
                    "comment:admin"
                ]
            }
        }
    }
}

```

<a id="cs/latest/developer-resources/security/roles.html--patterns">

#### Patterns

The patterns facilitate determining permissions to a group of documents. You can provide a pattern with wildcard characters instead of the document ID. The pattern will then cover multiple documents IDs.

Example: The following sample defines a user that has the `reader` role in all documents matching the pattern: `docs-*`. Examples of matching documents could be: `docs-titlepage` and `docs-category-document`.

```
{
    "auth": {
        "collaboration": {
            "docs-*": {
                "role": "reader"
            }
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html">source file: "cs/latest/developer-resources/security/token-endpoint.html"</a>

## Token endpoint

<a id="cs/latest/developer-resources/security/token-endpoint.html--token-endpoint-overview">

### Token endpoint overview

To connect [CKEditor 5](https://ckeditor.com/ckeditor-5/) or [CKEditor 4](https://ckeditor.com/ckeditor-4/) with CKEditor Cloud Services, you need to create your own token endpoint. This guide will explain a few principles that you need to know to create it.

<a id="cs/latest/developer-resources/security/token-endpoint.html--how-ckeditor-cloud-services-uses-tokens">

### How CKEditor Cloud Services uses tokens

To authenticate users, CKEditor Cloud Services uses tokens. The purpose of tokens is to inform the cloud services that the user has access to resources and to which environment the user should connect to. The authenticity of tokens is provided by a digital signature.

The token endpoint is where the client using CKEditor makes a request to get the token. It should return the token only if the user proves their identity.

The token endpoint should be placed inside of your system.

<a id="cs/latest/developer-resources/security/token-endpoint.html--the-json-web-tokens-specification">

### The JSON Web Tokens specification

CKEditor Cloud Services tokens are represented as JSON Web Tokens (JWT). JWT is an open [standard](https://tools.ietf.org/html/rfc7519) for transmitting digitally signed information. Using it ensures that the data comes from a trusted source.

The tokens consist of three parts:

* header
* payload
* signature

Each part is encoded in `base64url` and separated by periods:

```
header.payload.signature

```

An example token can look like this:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiSm9obiJ9.3MOd-0xmppWAX_86vMPjQ0PTKAniCtr762UTM5WuGa8

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--header">

#### Header

The header indicates that it is a JWT and defines the hashing algorithm for calculating the signature. It is simply a JSON object with the `typ` and `alg` properties, where `typ` always contains the `JWT` value and `alg` contains the name of the algorithm used.

<a id="cs/latest/developer-resources/security/token-endpoint.html--payload">

#### Payload

The payload is a JSON object with the claims. In CKEditor Cloud Services it is mostly used for specifying the environment, user data and permissions.

The JWT standard specifies some predefined claims like `aud` (audience), `exp` (expiration time), `sub` (subject) or `iat` (issued at). In CKEditor Cloud Services we use `aud` for identifying environments, `iat` for checking if the token has not expired and `sub` for identifying users.

<a id="cs/latest/developer-resources/security/token-endpoint.html--signature">

#### Signature

Unlike the header and the payload, the signature is not a JSON object but instead raw bytes produced by the cryptographic algorithm.

The signature is calculated for the header merged with the payload. It enables the authentication of data and verification that the token has not been tampered with:

```
signature = HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    secret
)

```

CKEditor Cloud Services supports signatures created by the `HS256`, `HS384` and `HS512` algorithms.

<a id="cs/latest/developer-resources/security/token-endpoint.html--token">

### Token

The token for the CKEditor Cloud Services should specify the `Environment ID` as the `aud` property and it needs to be signed with the `Access key`. Both can be found in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises - refer to the [documentation for environments management](#cs/latest/developer-resources/environments/environments-management.html). Optionally, the token can contain the user data. Otherwise CKEditor Cloud Services will treat the user as an anonymous user.

<a id="cs/latest/developer-resources/security/token-endpoint.html--user">

#### User

If the user is not anonymous, the payload should contain the `sub` claim, which identifies the user. You can also put a `user` object to define other properties like `name`, `email` or `avatar`. In the case of an anonymous user, a random user ID will be generated.

<a id="cs/latest/developer-resources/security/token-endpoint.html--billings">

#### Billings

While using CKEditor Cloud Services in the SaaS variant, **you will be billed for every unique user**. Customers who use the On-Premises variant of the CKEditor Collaboration Server are limited by the number of unique connected users.

A unique user is counted based on a unique pair of the `aud`(environment ID) and `sub`(user ID) properties from the token. In the case of an anonymous user, every user will be billed separately as a random user ID will be assigned.

<a id="cs/latest/developer-resources/security/token-endpoint.html--token-payload">

#### Token payload

<a id="cs/latest/developer-resources/security/token-endpoint.html--payload-properties">

##### Payload properties

The following properties **must** be included in the payload:

* `aud` – The environment ID.
* `iat` – “Issued at”. Make sure that `iat` is present and contains a correct time stated in seconds. Some JWT implementations do not include it by default. Sometimes the system time may also be invalid, causing weird issues with tokens (see e.g. [Docker for Mac time drift](https://github.com/docker/for-mac/issues/2076)).
* `auth` – Permissions for the services being used. If you plan to use collaboration, the `auth.collaboration` roles are required. If you plan to use CKEditor AI, the `auth.ai.permissions` array is required. If you just use Export to Word/PDF, you may skip it.

The properties that are optional:

* `sub` – The user ID.
* `user` – User information. Providing `name` and `email` is recommended.
* `exp` – Token expiration time. Identifies the expiration time after which the JWT will not be accepted. Cloud Services only accept tokens no older than 24 hours. This field can be used to shorten the token validity time.

<a id="cs/latest/developer-resources/security/token-endpoint.html--roles-and-permissions">

##### Roles and permissions

To define permissions to resources, the token payload should include the `auth` object with specified user roles and/or permissions.

```
{
    "auth": {
        "collaboration": {
            "doc-1": {
                "role": "writer"
            },
            "doc-2": {
                "role": "commentator",
                "permissions": [
                    "comment:admin"
                ]
            },
            "doc-3": {
                "permissions": [
                    "document:read",
                    "document:write",
                    "comment:read"
                ]
            }
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--ai-permissions">

##### AI permissions

To control access to CKEditor AI features, the token payload should include the `auth.ai.permissions` array. Each permission follows the format `ai:<permission-type>:<permission-value>`.

```
{
    "auth": {
        "ai": {
            "permissions": [
                "ai:conversations:*",
                "ai:models:agent",
                "ai:actions:system:*",
                "ai:reviews:system:*"
            ]
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--example-token-payload-for-collaboration">

##### Example token payload for collaboration

The example below presents a complete token payload with access to editing all documents in the environment:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "exampleuser",
    "user": {
        "email": "example@cksource.com",
        "name": "A User",
        "avatar": "http://example.com/avatars/john.png"
    },
    "auth": {
        "collaboration": {
            "*": {
                "role": "writer"
            }
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--example-token-payload-for-ai">

##### Example token payload for AI

The example below presents a token payload granting access to AI conversations, actions, and reviews with the recommended `agent` model:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "exampleuser",
    "auth": {
        "ai": {
            "permissions": [
                "ai:conversations:*",
                "ai:models:agent",
                "ai:actions:system:*",
                "ai:reviews:system:*"
            ]
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--example-token-payload-for-collaboration-and-ai">

##### Example token payload for collaboration and AI

When using both collaboration and AI features together, include both `auth.collaboration` and `auth.ai` in the same token:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "exampleuser",
    "user": {
        "email": "example@cksource.com",
        "name": "A User"
    },
    "auth": {
        "collaboration": {
            "*": {
                "role": "writer"
            }
        },
        "ai": {
            "permissions": [
                "ai:conversations:*",
                "ai:models:agent",
                "ai:actions:system:*",
                "ai:reviews:system:*"
            ]
        }
    }
}

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--requests-to-the-token-endpoint">

### Requests to the token endpoint

The token for CKEditor Cloud Services is requested by the CKEditor 5 [real-time collaborative editing](https://ckeditor.com/collaboration/real-time-collaborative-editing/).

<a id="cs/latest/developer-resources/security/token-endpoint.html--simple-usage">

#### Simple usage

<a id="cs/latest/developer-resources/security/token-endpoint.html--ckeditor-5">

##### CKEditor 5

The easiest way to request the token endpoint is to set the [config.cloudServices.tokenUrl](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) option to the endpoint. It will be requested from the editor by the [Cloud Services plugin](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservices-CloudServices.html) with a simple HTTP request at the initialization stage and then after every hour.

```
ClassicEditor.create( element, {
    // ...
    cloudServices: {
        tokenUrl: 'https://example.com/cs-token-endpoint'
    }
} );

```

If you need more control over the request, refer to the [Customizing the token request method](#cs/latest/developer-resources/security/token-endpoint.html--customizing-the-token-request-method) section below.

<a id="cs/latest/developer-resources/security/token-endpoint.html--ckeditor-4">

##### CKEditor 4

The easiest way to request the token endpoint is to set the [cloudServices\_tokenUrl](https://ckeditor.com/docs/ckeditor4/latest/api/CKEDITOR%5Fconfig.html#cfg-cloudServices%5FtokenUrl) option to the endpoint. It will be requested from the editor with a simple HTTP request at the initialization stage and then again every hour.

```
CKEDITOR.replace( 'editor', {
    cloudServices_tokenUrl: 'https://example.com/cs-token-endpoint',
} );

```

You can find more information about the integration with CKEditor 4 in the [Easy Image Integration guide](https://ckeditor.com/docs/ckeditor4/latest/guide/dev%5Feasyimage%5Fintegration.html).

<a id="cs/latest/developer-resources/security/token-endpoint.html--customizing-the-token-request-method">

#### Customizing the token request method

<a id="cs/latest/developer-resources/security/token-endpoint.html--ckeditor-5-2">

##### CKEditor 5

If you would like to change the default method of requesting the token from the server (described in the previous section), you can set the [config.cloudServices.tokenUrl](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-tokenUrl) option to a callback. This callback will be used by the [Cloud Services plugin](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservices-CloudServices.html) to retrieve the token. It allows specifying exact HTTP request parameters for the token endpoint that should return the token value. The callback needs to return a promise that will be resolved with the token value or rejected with an error.

An example below presents setting a custom callback to the `tokenUrl` configuration that adds a custom header to the request:

```
const tokenUrl = 'https://example.com/cs-token-endpoint';

ClassicEditor.create( element, {
    // ...
    cloudServices: {
        tokenUrl: () => {
            return new Promise( ( resolve, reject ) => {
                const xhr = new XMLHttpRequest();

                xhr.open( 'GET', tokenUrl );

                xhr.addEventListener( 'load', () => {
                    const statusCode = xhr.status;
                    const xhrResponse = xhr.response;

                    if ( statusCode < 200 || statusCode > 299 ) {
                        return reject( new Error( 'Cannot download a new token!' ) );
                    }

                    return resolve( xhrResponse );
                } );

                xhr.addEventListener( 'error', () => reject( new Error( 'Network error' ) ) );
                xhr.addEventListener( 'abort', () => reject( new Error( 'Abort' ) ) );

                xhr.setRequestHeader( customHeader, customValue );

                xhr.send();
            } );
        }
    }
} );

```

The current token value is accessible via the `CloudServices` plugin.

```
const cloudServices = editor.plugins.get( 'CloudServices' );
const tokenValue = cloudServices.token.value;

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--responses-from-the-token-endpoint">

### Responses from the token endpoint

The endpoint should respond with a generated token in the form of a string.

An example response might look like this:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiSm9obiJ9.3MOd-0xmppWAX_86vMPjQ0PTKAniCtr762UTM5WuGa8

```

<a id="cs/latest/developer-resources/security/token-endpoint.html--tools">

### Tools

We highly recommend using the libraries listed on [jwt.io](https://jwt.io/#libraries-io) to create the token. You can also check our token endpoint implementation examples in the following languages:

* [ASP.NET](#cs/latest/examples/token-endpoints/dotnet.html),
* [Java](#cs/latest/examples/token-endpoints/java.html),
* [Node.js](#cs/latest/examples/token-endpoints/nodejs.html),
* [PHP](#cs/latest/examples/token-endpoints/php.html),
* [Python](#cs/latest/examples/token-endpoints/python.html),

If you encounter problems creating the token endpoint in another server-side language, or if you have any other suggestions regarding the documentation, please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/developer-resources/security/token-endpoint.html--most-common-issues">

### Most common issues

<a id="cs/latest/developer-resources/security/token-endpoint.html--invalid-token">

#### Invalid token

```
CKEditorError: cloud-services-internal-error: Invalid token. Error Trace id: <TRACE ID>. Read more: <https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/error-codes.html#error-cloud-services-internal-error> {"errors":[]}

```

Check if the token was created in accordance with our [standards](#cs/latest/developer-resources/security/token-endpoint.html--responses-from-the-token-endpoint). You can also refer to our [token endpoint examples](#cs/latest/examples/token-endpoints/nodejs.html).  
Please also ensure that you are using a correct and valid [access key](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) which is assigned to the right environment.  
You can validate the token using the [jwt.io debugger](https://jwt.io/#encoded-jwt).

<a id="cs/latest/developer-resources/security/token-endpoint.html--you-dont-have-enough-permissions-to-access-this-resource">

#### You don’t have enough permissions to access this resource

```
CKEditorError: cloud-services-internal-error: You don't have enough permissions to access this resource. Error Trace id: <TRACE ID>. Read more: <https://ckeditor.com/docs/ckeditor5/latest/framework/guides/support/error-codes.html#error-cloud-services-internal-error> {"errors":[]}

```

Please ensure that your token endpoint includes the right roles for the requested resource.  
You can read more about the role mechanism in the [Roles guide](#cs/latest/developer-resources/security/roles.html).

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html">source file: "cs/latest/developer-resources/server-side-editor-api/editor-scripts.html"</a>

## Editor scripts

The Server-side Editor API can be accessed through the `POST /collaborations/{document_id}/evaluate-script` endpoint from the [REST API](https://help.cke-cs.com/api/docs). This endpoint allows you to execute JavaScript code that uses the CKEditor–5 API directly on the Cloud Services server.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--prerequisites">

### Prerequisites

* An [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) needs to be uploaded.
* The source document needs to be created after uploading the editor bundle.
* The source document needs to have an active collaboration session. You can initialize the document session programatically via [import collaboration session content directly from storage](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations/post) REST endpoint.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--request-structure">

### Request Structure

The request body should contain a `script` parameter with the JavaScript code to be executed:

```
{
    "script": "// Your JavaScript code here that uses the CKEditor 5 API"
}

```

The `script` parameter should contain valid JavaScript code that can access the CKEditor–5 API. The script has access to:

* **Editor instance**: The CKEditor–5 editor instance is available in the script context
* **Document model**: Access to the document’s data model for content manipulation
* **Editor plugins**: All loaded plugins and their APIs
* **Collaboration features**: Access to comments, suggestions, and revision history

It should be a properly formatted string according to `ECMA-404 (The JSON Data Interchange Standard)`. The only characters you must escape are `\` and `"`. Control codes such as `\n`, `\t`, etc., can be removed or escaped as well.

You can also include a `user` object in the request body to control the user details, like name, during script execution. The `hidden_in_presence_list` property allows you to hide the user from the presence list in the collaboration session, which is useful for server-side script executions that should not appear as active users.

The example below shows a basic script for getting editor data, along with user context configuration that allows you to execute scripts with specific user context and to control how the user appears in the collaboration session:

```
{
    "script": "return editor.getData()",
    "user": {
        "id": "user-123",
        "name": "John Doe",
        "hidden_in_presence_list": true
    }
}

```

You can specify a `plugins_to_remove` parameter in the request body to provide a list of plugin names for removal from the editor before executing the script. It is useful when you need to disable certain editor features or plugins that might interfere with your script execution. Note that, it is different from the `removePlugins` option that you may have specified in the editor bundle configuration during the bundle upload, as it permanently excludes those plugins from typical document conversions. The `removePlugins` option is often used to exclude plugins that communicate with the internet. However, in the case of the Server-side Editor API, such plugins can be included in your editor bundle and used in scripts if needed.

```
{
    "script": "return editor.getData()",
    "plugins_to_remove": ["DocumentOutline", "ExportInlineStyles"]
}

```

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--syntax">

#### Syntax

Scripts can be written in both async and non-async ways. You can use `await` for asynchronous operations:

```
// Non-async script
editor.getData();

// Async script
await Promise.resolve( editor.getData() );

```

You can return data from your script using the `return` statement. The returned value will be available as literal data or as a JSON (in case of an object) in the API response:

```
// Return processed data
const content = editor.getData();

return {
    content: content,
    wordCount: content.split(' ').length
};

```

The CKEditor 5 editor instance is available globally as the `editor` object. You can access all editor methods and properties:

```
// Get editor content
const content = editor.getData();

// Set editor content
editor.setData('<p>New content</p>', { suppressErrorInCollaboration: true } );

// Access editor model
const model = editor.model;

// Use editor commands
editor.execute('bold');

```

Scripts have access to most browser and JavaScript APIs, with some restrictions for security reasons.

Refer to the [security considerations](#cs/latest/developer-resources/server-side-editor-api/security.html) guide for detailed implementation.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--authentication">

#### Authentication

All requests to the Server-side Editor API require proper authentication using:

* `X-CS-Timestamp` header with the current timestamp
* `X-CS-Signature` header with a valid request signature

Refer to the [request signature](#cs/latest/developer-resources/security/request-signature.html) guide for detailed implementation.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--response">

#### Response

The API returns a `201` status code on successful execution. The response contains the data returned by your script under the `data` attribute:

```
{
  "data": "<p>Editor content</p>"
}

```

For objects returned by your script, the response will be:

```
{
  "data": {
    "content": "<p>Editor content</p>",
    "wordCount": 5
  }
}

```

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--error-handling">

#### Error handling

When a script fails to execute, the API returns detailed error information. Example error response:

```
{
    "message": "Editor script failed to evaluate",
    "trace_id": "2daa364a-a658-4123-9630-50497447ed07",
    "status_code": 400,
    "data": {
        "error": {
            "name": "TypeError",
            "message": "Cannot read properties of undefined (reading 'get')",
            "details":[
                "Cannot read properties of undefined (reading 'change')"
            ]
        }
    },
    "level": "trace",
    "explanation": "The provided script cannot be evaluated due to the attached error",
    "action": "Please check the error and script syntax or contact support if the problem persists"
}

```

The `data.error.details` field contains an array of intercepted and parsed browser console errors, which can help you identify the root cause of script execution failures.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--debugging-and-testing">

#### Debugging and Testing

When developing and testing your editor scripts, you can enable the debug mode by setting the `debug: true` parameter in your API request. This will allow you to collect the `console.debug` logs from the script execution. It can be helpful for troubleshooting and understanding script behavior.

```
{
    "script": "console.debug('Processing editor data', { wordCount: editor.getData().length }); return editor.getData();",
    "debug": true
}

```

With debug mode enabled, any `console.debug()` calls in your script will be captured and included in the response. This provides additional insight into your script’s execution flow:

```
{
    "data": "<p>Editor content</p>",
    "metadata": {
        "logs": [
            {
                "type": "debug",
                "createdAt": "2025-08-08T12:00:00.000Z",
                "data": [
                    "Processing editor data",
                    { "wordCount": 245 }
                ]
            }
        ]
    }
}

```

In order to improve the debugging experience in case of an error tracking process, the evaluation error also includes the collected `logs` during the script evaluation. This means that if a script fails to execute when debug mode is enabled, you will receive both the error details and any debug logs that were captured before the failure occurred, providing valuable context for troubleshooting script issues.

```
{
    "message": "Editor script failed to evaluate",
    "trace_id": "2daa364a-a658-4123-9630-50497447ed07",
    "status_code": 400,
    "data": {
        "error": {
            "name": "TypeError",
            "message": "Cannot read properties of undefined (reading 'get')",
        },
        "logs": [
            {
                "createdAt": "2025-08-08T12:00:00.000Z",
                "type": "debug",
                "data": [
                    "Processing editor data",
                    { "wordCount": 245 }
                ]
            }
        ]
    },
    "explanation": "The provided script cannot be evaluated due to the attached error",
    "action": "Please check the error and script syntax or contact support if the problem persists"
}

```

Please remember, that only serializable objects can be outputted in debug logs. Custom error attributes and non-serializable content will be omitted from the response.

<a id="cs/latest/developer-resources/server-side-editor-api/editor-scripts.html--next-steps">

### Next steps

* [Server-side Editor API security considerations](#cs/latest/developer-resources/server-side-editor-api/security.html)

<a id="cs/latest/developer-resources/server-side-editor-api/security.html">source file: "cs/latest/developer-resources/server-side-editor-api/security.html"</a>

## Server-side Editor API security considerations

The Server-side Editor API includes security measures to prevent malicious code execution. All scripts are analyzed before the execution to detect and block potentially dangerous operations.

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--restricted-operations">

### Restricted Operations

The following categories of operations are blocked for security reasons:

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--global-functions-and-apis">

#### Global Functions and APIs

The API blocks access to potentially dangerous global functions and APIs that could be used for malicious purposes:

* **Code execution functions**: `eval`, `Function`, `importScripts`
* **Timing functions**: `setTimeout`, `setInterval`, `requestAnimationFrame`
* **Network and communication**: `XMLHttpRequest`, `WebSocket`, `Worker`, `SharedWorker`, `BroadcastChannel`
* **File and data access**: `FileReader`, `indexedDB`
* **Encoding/decoding**: `atob`, `btoa`, `decodeURIComponent`
* **Storage access**: `localStorage`, `sessionStorage`
* **Browser navigation**: `history`, `import`
* **Performance monitoring**: `performance`

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--browser-apis-and-document-manipulation">

#### Browser APIs and Document Manipulation

Access to browser-specific APIs is restricted to prevent unauthorized document manipulation and browser state changes:

* **Document creation and modification**: `document.createElement`, `document.write`, `document.writeln`, `document.createElementNS`
* **Document properties**: `document.cookie`, `document.body`, `document.head`, `document.location`
* **Window operations**: `window.open`, `window.location`, `window.postMessage`, `window.btoa`, `window.atob`, `window.document`, `window.navigator`, `window.performance`
* **URL manipulation**: `URL.createObjectURL`
* **Browser information**: `navigator.sendBeacon`, `navigator.userAgent`, `navigator.platform`
* **Performance data**: `performance.now`, `performance.getEntries`
* **History manipulation**: `history.pushState`, `history.replaceState`

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--element-operations">

#### Element Operations

Direct manipulation of DOM elements is blocked to prevent injection attacks:

* **HTML injection**: `element.innerHTML`, `element.outerHTML`, `element.insertAdjacentHTML`
* **Event handling**: `element.addEventListener`

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--constructor-calls">

#### Constructor Calls

Creating certain objects is restricted to prevent potential security vulnerabilities:

* **File objects**: `new Blob()`, `new File()`, `new FileReader()`
* **Communication objects**: `new WebSocket()`, `new Worker()`, `new SharedWorker()`, `new BroadcastChannel()`
* **Code execution**: `new Function()`
* **URL objects**: `new URL()`

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--url-schemes">

#### URL Schemes

Certain URL schemes are blocked to prevent code injection and data leakage:

* **Data URLs**: `data:`
* **Blob URLs**: `blob:`
* **JavaScript URLs**: `javascript:`
* **VBScript URLs**: `vbscript:`

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--security-violations">

### Security Violations

If your script contains restricted operations, the API will return an error with details about the violation, including the line and column position.

<a id="cs/latest/developer-resources/server-side-editor-api/security.html--next-steps">

### Next steps

* [Server-side Editor API Node.js example](#cs/latest/examples/server-side-editor-api-examples/extract-document-content-in-nodejs.html)

<a id="cs/latest/developer-resources/webhooks/events.html">source file: "cs/latest/developer-resources/webhooks/events.html"</a>

## Events

Each event corresponds with a certain action that can happen in CKEditor Cloud Services in a certain environment. Also, each event has a specific payload format with the relevant event information.  
Before you use Webhooks, please get familiar with the basic principals of the feature. You can read more about how to use Webhooks in [the Overview article](#cs/latest/developer-resources/webhooks/overview.html).

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration">

### Collaboration

The following events can be triggered for the Collaboration service.

<a id="cs/latest/developer-resources/webhooks/events.html--user-connected">

#### User connected

Name: `collaboration.user.connected` (previously `document.user.connected`)  
Description: Triggered when a user joins a collaboration session.

<a id="cs/latest/developer-resources/webhooks/events.html--payload">

##### Payload

* `document.id` – The ID of the document that the user connected to.
* `user.id` – The ID of the user.
* `connected_users` – The list of currently connected users.

<a id="cs/latest/developer-resources/webhooks/events.html--example">

##### Example

The following example presents a webhook request sent after a user connected to the document.

```
{
    "event": "collaboration.user.connected",
    "environment_id": "environment-1",
    "payload": {
        "user": {
            "id": "user-1"
        },
        "document": {
            "id": "document-1"
        },
        "connected_users": [
            {
                "id": "user-2"
            }
        ]
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--user-disconnected">

#### User disconnected

Name: `collaboration.user.disconnected` (previously `document.user.disconnected`)  
Description: Triggered when a user disconnects from an active collaboration session.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-2">

##### Payload

* `document.id` – The ID of the document that the user disconnected from.
* `user.id` – The ID of the user.
* `connected_users` – The list of currently connected users.

<a id="cs/latest/developer-resources/webhooks/events.html--example-2">

##### Example

The following example presents a webhook request sent after a user disconnected from the document.

```
{
    "event": "collaboration.user.disconnected",
    "environment_id": "environment-1",
    "payload": {
        "user": {
            "id": "user-1"
        },
        "document": {
            "id": "document-1"
        },
        "connected_users": [
            {
                "id": "user-2"
            }
        ]
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-updated">

#### Collaboration session updated

Name: `collaboration.document.updated`  
Description: Triggered every 10 minutes or 5000 versions when the content of the collaboration session is being updated. The event will also be emitted when the last user disconnects from a collaboration session.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-3">

##### Payload

* `document.id` – The ID of the updated document.
* `document.updated_at` – The date of the document update.
* `document.updated_by` – The ID of the last user performing the update.
* `document.version` – The version of the updated document.

<a id="cs/latest/developer-resources/webhooks/events.html--example-3">

##### Example

The following example presents a webhook request sent after a document is updated.

```
{
  "event": "collaboration.document.updated",
  "environment_id": "environment-1",
  "payload": {
      "document": {
          "id": "document-1",
          "updated_at": "2019-05-29T08:17:56.761Z",
          "updated_by": "user-1",
          "version": 2000
      }
  },
  "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-update-exported">

#### Collaboration session update exported

Name: `collaboration.document.update.exported`  
Description: Triggered every 10 minutes or 5000 versions when the content of the collaboration session is being updated. The webhook is also triggered when the collaboration session ends and when the last user disconnects. It contains a document content session. All the following conditions have to be met:

1. The [editorBundle](#cs/latest/guides/collaboration/editor-bundle.html) is uploaded.
2. The document storage feature is disabled.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-4">

##### Payload

* `document.id` – The ID of the updated document.
* `document.updated_at` – The date of the document update.
* `document.version` – The version of the updated document.
* `document.status` – The status of an export.
* `document.data` – The document content. The property can be empty if exporting a collaboration session failed.
* `document.attributes` – The document attributes object. The property may be sent when a document has been exported from a multi-root editor.

<a id="cs/latest/developer-resources/webhooks/events.html--example-4">

##### Example

The following example presents a webhook request sent after a document is updated.

```
{
    "event": "collaboration.document.update.exported",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "exported_at": "2019-05-29T08:17:56.761Z",
            "version": 2000,
            "status": "success",
            "data": "<p>Document content</p>",
            "attributes": { "foo": "bar" }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-finished">

#### Collaboration session finished

Name: `collaboration.document.finished`  
Description: Triggered when a collaboration session for a document has ended and the [temporary data of the document](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data) has been removed. The webhook is triggered regardless of the document storage configuration. To receive the exported document data, use the `collaboration.document.exported` webhook.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-5">

##### Payload

* `document.id` – The ID of the removed document.
* `document.removed_at` – The date of the document removal.

<a id="cs/latest/developer-resources/webhooks/events.html--example-5">

##### Example

The following example presents a webhook request sent after a collaboration session for a document has ended:

```
{
    "event": "collaboration.document.finished",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "removed_at": "2019-05-29T08:17:56.761Z"
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-exported">

#### Collaboration session exported

Name: `collaboration.document.exported`  
Description: Triggered whenever all of the following conditions are met:

1. A collaboration session has ended.
2. The document data has been successfully exported.
3. The [editorBundle](#cs/latest/guides/collaboration/editor-bundle.html) is uploaded.
4. The document storage is disabled.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-6">

##### Payload

* `document.id` – The ID of the removed document.
* `document.data` – The data of the removed document.
* `document.removed_at` – The date when the document has been removed.
* `document.version` – The version of the removed document.
* `document.attributes` – The document attributes object. The property may be sent when a document has been exported from a multi-root editor.

<a id="cs/latest/developer-resources/webhooks/events.html--example-6">

##### Example

The following example presents a webhook request sent after a collaboration session has ended and the document data has been successfully exported:

```
{
    "event": "collaboration.document.exported",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "data": "<p>Document content</p>",
            "removed_at": "2019-05-29T08:16:12.755Z",
            "version": 10,
            "attributes": { "foo": "bar" }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-export-failed">

#### Collaboration session export failed

Name: `collaboration.document.export.failed`  
Description: Triggered whenever both of the following conditions are met: (1) the system cannot convert document operations after a collaboration session has ended, and (2) the document storage is disabled.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-7">

##### Payload

* `document.id` – The ID of the removed document.
* `document.reason` – The reason of the failed document operations conversion.
* `document.removed_at` – The date when the document has been removed.
* `document.version` – The version of the removed document.

<a id="cs/latest/developer-resources/webhooks/events.html--example-7">

##### Example

The following example presents a webhook request sent after a collaboration session for a document has ended, but some of its operations could not be applied:

```
{
    "event": "collaboration.document.export.failed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "reason": "general-conversion-fail",
            "removed_at": "2019-05-29T08:16:12.755Z",
            "version": 10
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-recovered">

#### Collaboration session recovered

Name: `collaboration.document.recovered`  
Description: Triggered when a collaboration session for a document has expired and the [temporary data of the document](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data) have been removed but some of the document operations could not be applied. The webhook is sent only when the [document storage feature](#cs/latest/guides/collaboration/document-storage.html) is disabled, and it will contain only correctly applied operations.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-8">

##### Payload

* `document.id` – The ID of the removed document.
* `document.removed_at` – The date of the document removal.
* `document.data` – The data of the removed document including only the successfully applied operations.
* `document.version` – The version of the removed document.
* `document.attributes` – The document attributes object. The property may be sent when a document has been exported from a multi-root editor.

<a id="cs/latest/developer-resources/webhooks/events.html--example-8">

##### Example

The following example presents a webhook request sent after a document has been removed but some of its operations could not be applied.

```
{
    "event": "collaboration.document.recovered",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "removed_at": "2019-05-29T08:17:56.761Z",
            "data": "<p>Document content</p>",
              "version": 10,
            "attributes": { "foo": "bar" }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--document-storage">

### Document storage

<a id="cs/latest/developer-resources/webhooks/events.html--document-saved">

#### Document saved

Name: `storage.document.saved`  
Description: Triggered when the document data is saved.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-9">

##### Payload

* `document.id` – The ID of the saved document.
* `document.saved_at` – The date of the document save.
* `document.download_url` – The URL to download the document.
* `document.attributes` – The document attributes object. The property may be sent when a document has been exported from a multi-root editor.

<a id="cs/latest/developer-resources/webhooks/events.html--example-9">

##### Example

The following example presents a webhook request sent after a document is saved.

```
{
    "event": "storage.document.saved",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "saved_at": "2019-05-29T08:17:56.761Z",
            "download_url": "/api/v5/environment-1/storage/document-1",
              "attributes": { "foo": "bar" }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--document-save-failed">

#### Document save failed

Name: `storage.document.save.failed`  
Description: Triggered when a document data save has failed. It may happen when a different editor bundle or its configuration is used on your website and the CKEditor Cloud Services server under the same [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion). Refer to the [Editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) guide for more information.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-10">

##### Payload

* `document.id` – The ID of the document.
* `document.failed_at` – The date of the document save failure.
* `editor.bundleVersion` – The `bundleVersion` of the editor used during the save.
* `fail.reason` – The reason of the document save failure.
* `fail.details` – The details of the document save failure.
* `fail.trace_id` – The trace ID of the document save failure.

<a id="cs/latest/developer-resources/webhooks/events.html--example-10">

##### Example

The following example presents a webhook request sent after a document data save has failed.

```
{
    "event": "storage.document.save.failed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "failed_at": "2019-05-29T08:17:56.761Z"
        },
        "editor": {
            "bundleVersion": "some_unique_bundle_version"
        },
        "fail": {
            "reason": "Error while processing document.",
            "details": "model-position-fromjson-no-root: Cannot create position for document.",
            "trace_id": "trace-id-1"
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--document-removed">

#### Document removed

Name: `storage.document.removed`  
Description: Triggered when the document data is removed from the storage. The document can be removed using a REST API call (see the [Storage](https://help.cke-cs.com/api/docs#tag/Storage) REST API section) or when the document storage feature is being turned off. After you disable the feature in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises, all stored documents are removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-11">

##### Payload

* `document.id` – The ID of the document.
* `document.removed_at` – The date of the document removal.
* `document.data` – The data of the removed document.
* `document.attributes` – The document attributes object. The property may be sent when a document has been exported from a multi-root editor.

<a id="cs/latest/developer-resources/webhooks/events.html--example-11">

##### Example

The following example presents a webhook request sent after a document is removed from the storage.

```
{
    "event": "storage.document.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "removed_at": "2019-05-29T08:17:56.761Z",
            "data": "<p>Document content</p>",
            "attributes": { "foo": "bar" }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comments">

### Comments

The following events can be triggered for the Comments service.

<a id="cs/latest/developer-resources/webhooks/events.html--comment-added">

#### Comment added

Name: `comment.added`  
Description: Triggered when a comment is created.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-12">

##### Payload

* `document.id` – The ID of the document in which the comment was added.
* `comment.id` – The ID of the added comment.
* `comment.created_at` – The creation date of the comment.
* `comment.content` – The content of the added comment.
* `comment.attributes` – The attributes of the added comment.
* `comment.thread_id` – The thread ID that the comment was added to.
* `comment.user.id` – The ID of the author of the comment.
* `comment.thread` – The optional field sent with data regarding comment archive feature.
* `comment_thread.id` – The ID of the added comment thread.
* `comment.thread.created_at` – The date of the comment thread creation.
* `comment.thread.context` – The context of the comment thread, required for the comments archive feature.
* `comment.thread.attributes` – The attributes of the added comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-12">

##### Example

The following example presents a webhook request sent after a comment is added.

```
{
    "event": "comment.added",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment": {
            "id": "comment-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "content": "Some comment content.",
            "attributes": { "foo": "bar" },
            "thread_id": "thread-1",
            "user": {
                "id": "user-1"
            },
          "thread": {
            "id": "thread-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "context": {
              "type": "value"
            },
            "attributes": {
              "attribute": "value"
            }
          }
        }
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-updated">

#### Comment updated

Name: `comment.updated`  
Description: Triggered when a comment is updated.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-13">

##### Payload

* `document.id` – The ID of the document in which the comment was updated.
* `comment.id` – The ID of the updated comment.
* `comment.updated_at` – The date of the comment update.
* `comment.content` – The content of the updated comment.
* `comment.old_content` – The old content of the updated comment.
* `comment.attributes` – The attributes of the updated comment.
* `comment.old_attributes` – The old attributes of the updated comment.
* `comment.thread_id` – The thread ID in which the comment was updated.
* `comment.user.id` – The ID of the author of the updated comment.
* `comment.thread` – The optional field sent with data regarding comment archive feature.
* `comment_thread.id` – The ID of the added comment thread.
* `comment.thread.created_at` – The date of the comment thread creation.
* `comment.thread.context` – The context of the comment thread, required for the comments archive feature.
* `comment.thread.resolved_at` – The date of the comment thread resolve. Sent only when a comment thread is resolved.
* `comment.thread_resolved_by` – The id of the user who resolved the comment thread. Sent only when a comment thread is resolved.
* `comment.thread.attributes` – The attributes of the added comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-13">

##### Example

The following example presents a webhook request sent after a comment is updated.

```
{
  "event": "comment.updated",
  "environment_id": "environment-1",
  "payload": {
    "document": {
      "id": "doc-1"
    },
    "comment": {
      "id": "comment-1",
      "updated_at": "2019-05-29T08:17:53.450Z",
      "content": "Some comment content.",
      "old_content": "Some old comment content.",
      "attributes": {
        "foo": "new"
      },
      "old_attributes": {
        "foo": "old"
      },
      "thread_id": "thread-1",
      "user": {
        "id": "user-1"
      },
      "thread": {
        "id": "thread-1",
        "created_at": "2019-05-29T08:17:53.450Z",
        "context": {
          "type": "value"
        },
        "resolved_at": "2019-05-29T08:17:53.450Z",
        "resolved_by": "user-1",
        "attributes": {
          "attribute": "value"
        }
      }
    }
  },
  "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-removed">

#### Comment removed

Name: `comment.removed`  
Description: Triggered when a comment is removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-14">

##### Payload

* `document.id` – The ID of the document from which the comment was removed.
* `comment.id` – The ID of the removed comment.
* `comment.removed_at` – The date of the comment removal.
* `comment.user.id` – The ID of the user who removed the comment.

<a id="cs/latest/developer-resources/webhooks/events.html--example-14">

##### Example

The following example presents a webhook request sent after a comment is removed.

```
{
    "event": "comment.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment": {
            "id": "comment-1",
            "removed_at": "2019-05-29T08:17:53.450Z",
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-added">

#### Comment thread added

Name: `commentthread.added`  
Description: Triggered when a comment thread is added.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-15">

##### Payload

* `document.id` – The ID of the document from which the comment thread was added.
* `comment_thread.id` – The ID of the added comment thread.
* `comment_thread.comments` – The list of comments from the added comment thread.
* `comment_thread.created_at` – The date of the comment thread creation.
* `comment_thread.context` – The context of the comment thread, required for the comments archive feature.
* `comment_thread.attributes` – The attributes of the added comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-15">

##### Example

The following example presents a webhook request sent after a comment thread is added.

```
{
  "event": "commentthread.added",
  "environment_id": "environment-1",
  "payload": {
    "document": {
      "id": "doc-1"
    },
    "comment_thread": {
      "id": "comment-thread-1",
      "comments": [
        {
          "id": "comment-1",
          "attributes": {
            "foo": "bar"
          },
          "content": "Some comment content",
          "user_id": "user-1",
          "created_at": "2019-05-29T08:17:53.450Z"
        }
      ],
      "created_at": "2019-05-29T08:17:53.450Z",
      "context": {
        "type": "value"
      },
      "attributes": {
        "attribute": "value"
      }
    }
  },
  "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-updated">

#### Comment thread updated

Name: `commentthread.updated`  
Description: Triggered when a comment thread is updated.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-16">

##### Payload

* `document.id` – The ID of the document from which the comment thread was updated.
* `comment_thread.id` – The ID of the updated comment thread.
* `comment_thread.comments` – The list of comments IDs from the updated comment thread.
* `comment_thread.updated_at` – The date of the comment thread update.
* `comment_thread.updated_by` – The ID of the user who updated the comment thread.
* `comment_thread.context` – The updated context of the comment thread, required for the comments archive feature.
* `comment_thread.attributes` – The updated attributes of the comment thread.
* `comment_thread.unlinked_at` – The date the comment has been unlinked, meaning that the text it was assigned to is not present in the document anymore.

<a id="cs/latest/developer-resources/webhooks/events.html--example-16">

##### Example

The following example presents a webhook request sent after a comment thread is updated.

```
{
  "event": "commentthread.updated",
  "environment_id": "environment-1",
  "payload": {
    "document": {
      "id": "doc-1"
    },
    "comment_thread": {
      "id": "comment-thread-1",
      "comments": [
        {
          "id": "comment-1"
        }
      ],
      "updated_at": "2019-05-29T08:17:53.450Z",
      "updated_by": "user-1",
      "context": {
        "type": "value"
      },
      "attributes": {
        "attribute": "value"
      },
    "unlinked_at": "2019-05-29T08:17:53.450Z"
    }
  },
  "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-resolved">

#### Comment thread resolved

Name: `commentthread.resolved`  
Description: Triggered whenever a comment thread is resolved.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-17">

##### Payload

* `document.id` – The ID of the document from which the comment thread was resolved.
* `comment_thread.id` – The ID of the resolved comment thread.
* `comment_thread.comments` – The list of comment IDs from the resolved comment thread.
* `comment_thread.resolved_at` – The date when the comment thread was resolved.
* `comment_thread.resolved_by` – The id of the user who resolved the comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-17">

##### Example

The following example presents a webhook request sent after a comment thread is resolved.

```
{
  "event": "commentthread.resolved",
  "environment_id": "environment-1",
  "payload": {
    "document": {
      "id": "doc-1"
    },
    "comment_thread": {
      "id": "comment-thread-1",
      "comments": [
        {
          "id": "comment-1"
        }
      ],
      "resolved_at": "2019-05-29T08:17:53.450Z",
      "resolved_by": "user-1"
    }
  },
  "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-reopened">

#### Comment thread reopened

Name: `commentthread.reopened`  
Description: Triggered whenever a comment thread is reopened.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-18">

##### Payload

* `document.id` – The ID of the document from which the comment thread was reopened.
* `comment_thread.id` – The ID of the reopened comment thread.
* `comment_thread.comments` – The list of comment IDs from the reopened comment thread.
* `comment_thread.reopened_at` – The date whe the comment thread was reopened.
* `comment_thread.reopened_by` – The ID of the user who reopened the comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-18">

##### Example

The following example presents a webhook request sent after a comment thread is reopen.

```
{
  "event": "commentthread.reopened",
  "environment_id": "environment-1",
  "payload": {
    "document": {
      "id": "doc-1"
    },
    "comment_thread": {
      "id": "comment-thread-1",
      "comments": [
        {
          "id": "comment-1"
        }
      ],
      "reopened_at": "2019-05-29T08:17:53.450Z",
      "reopened_by": "user-1"
    }
  },
  "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-removed">

#### Comment thread removed

Name: `commentthread.removed`  
Description: Triggered when a comment thread is removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-19">

##### Payload

* `document.id` – The ID of the document from which the comment thread was removed.
* `comment_thread.id` – The ID of the removed comment thread.
* `comment_thread.removed_at` – The date of the comment thread removal.
* `comment_thread.removed_by` – The ID of the user who removed the comment thread.
* `comment_thread.comments` – The list of comments from the removed comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-19">

##### Example

The following example presents a webhook request sent after a comment thread is removed.

```
{
    "event": "commentthread.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment_thread": {
            "id": "comment-thread-1",
            "removed_at": "2019-05-29T08:17:53.450Z",
            "removed_by": "user-1",
            "comments": [
               {
                   "id": "comment-1"
               }
            ]
        }
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-thread-restored">

#### Comment thread restored

Name: `commentthread.restored`  
Description: Triggered when a comment thread is restored. A comment thread can be removed by removing the text in a document. The undo operation can restore the removed text but also restore the comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-20">

##### Payload

* `document.id` – The ID of the document where the comment thread was restored.
* `comment_thread.id` – The ID of the restored comment thread.
* `comment_thread.restored_at` – The date of the comment thread restoration.
* `comment_thread.restored_by` – The ID of the user who restored the comment thread.
* `comment_thread.comments` – The list of comments from the restored comment thread.

<a id="cs/latest/developer-resources/webhooks/events.html--example-20">

##### Example

The following example presents a webhook request sent after a comment thread is restored.

```
{
    "event": "commentthread.restored",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment_thread": {
            "id": "comment-thread-1",
            "restored_at": "2019-05-29T08:17:53.450Z",
            "restored_by": "user-1",
            "comments": [
               {
                   "id": "comment-1"
               }
            ]
        }
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--comment-threads-removed">

#### Comment threads removed

Name: `commentthread.all.removed`  
Description: Triggered when all comment threads in a document are removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-21">

##### Payload

* `document.id` – The ID of the document from which the comment threads were removed.
* `comment_threads` – The list of removed comment threads.
* `comment_threads[].id` – The ID of the removed comment thread.
* `comment_thread[].removed_at` – The date of the comment thread removal.
* `comment_thread[].comments` – The list of comments from the removed comment threads.

<a id="cs/latest/developer-resources/webhooks/events.html--example-21">

##### Example

The following example presents a webhook request sent after all comment threads are removed from a document.

```
{
    "event": "commentthread.all.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment_threads": [
            {
                "id": "comment-thread-1",
                "removed_at": "2019-05-29T08:17:53.450Z",
                "comments": [
                    {
                        "id": "comment-1"
                    }
                ]
            },
            {
                "id": "comment-thread-2",
                "removed_at": "2019-05-29T08:17:53.450Z",
                "comments": [
                    {
                        "id": "comment-2"
                    }
                ]
            }
        ]
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--suggestions">

### Suggestions

The following events can be triggered for the Track Changes service.

<a id="cs/latest/developer-resources/webhooks/events.html--suggestion-added">

#### Suggestion added

Name: `suggestion.added`  
Description: Triggered whenever a suggestion is added.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-22">

##### Payload

* `document.id` – The ID of the document in which the suggestion was added.
* `suggestion.id` – The ID of the suggestion.
* `suggestion.created_at` – The creation date of the suggestion.
* `suggestion.child_of` – The ID of the parent suggestion or null.
* `suggestion.user.id` – The ID of the author of the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--example-22">

##### Example

The following example presents a webhook request sent after a suggestion is added.

```
{
    "event": "suggestion.added",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1"
        },
        "suggestion": {
            "id": "suggestion-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "child_of": null,
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--suggestion-accepted">

#### Suggestion accepted

Name: `suggestion.accepted`  
Description: Triggered whenever a suggestion is accepted.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-23">

##### Payload

* `document.id` – The ID of the document in which the suggestion was added.
* `suggestion.id` – The ID of the suggestion.
* `suggestion.created_at` – The creation date of the suggestion.
* `suggestion.updated_at` – The date of the suggestion update/accept.
* `suggestion.user.id` – The ID of the user who accepted the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--example-23">

##### Example

The following example presents a webhook request sent after a suggestion is accepted.

```
{
    "event": "suggestion.accepted",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1"
        },
        "suggestion": {
            "id": "suggestion-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "updated_at": "2019-05-29T08:17:53.450Z",
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--suggestion-rejected">

#### Suggestion rejected

Name: `suggestion.rejected`  
Description: Triggered whenever a suggestion is rejected.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-24">

##### Payload

* `document.id` – The ID of the document in which the suggestion was added.
* `suggestion.id` – The ID of the suggestion.
* `suggestion.created_at` – The creation date of the suggestion.
* `suggestion.updated_at` – The date of the suggestion update/reject.
* `suggestion.user.id` – The ID of the user who reject the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--example-24">

##### Example

The following example presents a webhook request sent after a suggestion is rejected.

```
{
    "event": "suggestion.rejected",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1"
        },
        "suggestion": {
            "id": "suggestion-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "updated_at": "2019-05-29T08:17:53.450Z",
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--suggestion-removed">

#### Suggestion removed

Name: `suggestion.removed`  
Description: Triggered whenever a suggestion is removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-25">

##### Payload

* `document.id` – The ID of the document from which the suggestion was removed.
* `suggestion.id` – The ID of the suggestion.
* `suggestion.deleted_at` – The deletion date of the suggestion.
* `suggestion.user.id` – The ID of the user who removed the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--example-25">

##### Example

The following example presents a webhook request sent after a suggestion is removed.

```
{
    "event": "suggestion.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1"
        },
        "suggestion": {
            "id": "suggestion-1",
            "deleted_at": "2019-05-29T08:17:53.450Z",
            "user": {
                "id": "user-id"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--suggestion-restored">

#### Suggestion restored

Name: `suggestion.restored`  
Description: Triggered whenever a suggestion is restored. A suggestion can be removed by removing the text in a document. The undo operation can restore the removed text but also restore the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-26">

##### Payload

* `document.id` – The ID of the document where the suggestion was restored.
* `suggestion.id` – The ID of the suggestion.
* `suggestion.restored_at` – The restoration date of the suggestion.
* `suggestion.user.id` – The ID of the user who restored the suggestion.

<a id="cs/latest/developer-resources/webhooks/events.html--example-26">

##### Example

The following example presents a webhook request sent after a suggestion is restored.

```
{
    "event": "suggestion.restored",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1"
        },
        "suggestion": {
            "id": "suggestion-1",
            "restored_at": "2019-05-29T08:17:53.450Z",
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/events.html--deprecated">

### Deprecated

<a id="cs/latest/developer-resources/webhooks/events.html--collaboration-session-removed">

#### Collaboration session removed

Replaced by: `collaboration.document.finished` and `collaboration.document.exported`  
Name: `collaboration.document.removed` (previously `document.removed`)  
Description: Triggered when a collaboration session for a document expires and the [temporary data of the document](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data) is removed.

<a id="cs/latest/developer-resources/webhooks/events.html--payload-27">

##### Payload

* `document.id` – The ID of the removed document.
* `document.removed_at` – The date of the document removal.
* `document.data` – The data of the removed document. This is an **optional parameter** that is set when the [document storage feature](#cs/latest/guides/collaboration/document-storage.html) is disabled and the [editorBundle](#cs/latest/guides/collaboration/editor-bundle.html) is uploaded for the environment. If some of the operations cannot be applied to the document, the `data` property is empty and the `collaboration.document.recovered` webhook is emitted.

<a id="cs/latest/developer-resources/webhooks/events.html--example-27">

##### Example

The following example presents a webhook request sent after a document is removed.

```
{
    "event": "collaboration.document.removed",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "document-1",
            "removed_at": "2019-05-29T08:17:56.761Z",
            "data": "<p>Document content</p>"
        }
    },
    "sent_at": "2019-05-29T08:17:56.761Z"
}

```

<a id="cs/latest/developer-resources/webhooks/management.html">source file: "cs/latest/developer-resources/webhooks/management.html"</a>

## Webhooks management

Webhooks management is available for every environment in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for the On-Premises version.

Webhooks are managed separately for every environment. The environment you will manage can be selected from the list of environments by clicking in a row with an environment of choice.

<a id="cs/latest/developer-resources/webhooks/management.html--creating-webhooks">

### Creating webhooks

The webhooks can be managed on a dedicated page. To switch to the Webhooks section, click the `Webhooks` section in the left sidebar.  
The page shows existing webhooks and a button to add new ones.  
The list is empty until you define some webhooks for a particular environment.

To create a new webhook, click the `Create webhook` button.

The “Creating a webhook” page will show up.

While creating a new webhook, you need to provide a `Webhook URL` that CKEditor Cloud Services will send the requests to. The provided endpoint must be available from the CKEditor Collaboration On-premises application.

In the next section you can configure the retry mechanism, if enabled, the webhooks will be resent in the case when the response code from the Webhook URL endpoint will be larger than 299.

The Webhook request will be retried for of number provided in the `Max retries` times, or until the response status 2xx will be returned.  
Between each retry, there will be a delay, depending on the `Retry Interval in minutes` value.

The next section allows you to select [events](#cs/latest/developer-resources/webhooks/events.html) of which occurrence will trigger the webhook.

A single webhook can be triggered by many events, depending on a need.

[See the full list of available events in a dedicated article.](#cs/latest/developer-resources/webhooks/events.html)

To finish the process you need to click the `Create webhook` button at the very bottom of the form.  
The newly created Webhook will appear on the list in the main view of the `Webhooks` tabs.

<a id="cs/latest/developer-resources/webhooks/management.html--updating-webhook">

### Updating webhook

Each webhook visible in this list can be edited. It can be done by clicking the `Edit` button.

The button will open the “Editing a webhook” view. It presents exact same set of options as the “Create a new webhook” view.

You can change the Webhook URL, the set of events that will trigger the webhook, and the settings of the retry mechanism.

To save the changes you need to click the `Save changes` button at the very bottom of the form.

You will be redirected to the list of created webhooks.

<a id="cs/latest/developer-resources/webhooks/management.html--removing-webhook">

### Removing webhook

To remove a webhook use the remove button with an icon of a trash bin next to the selected webhook.

You will see the prompt to confirm the removal

<a id="cs/latest/developer-resources/webhooks/management.html--next-steps">

### Next steps

* [Read more about the request history in a dedicated article.](#cs/latest/developer-resources/webhooks/requests.html)
* [Read more about testing webhooks in a dedicated article.](#cs/latest/developer-resources/webhooks/testing.html)
* [Check the list of events available in CKEditor Cloud Services.](#cs/latest/developer-resources/webhooks/events.html)

<a id="cs/latest/developer-resources/webhooks/overview.html">source file: "cs/latest/developer-resources/webhooks/overview.html"</a>

## Webhooks

Webhooks resemble a notification mechanism that can be used to build integrations with CKEditor Cloud Services. CKEditor Cloud Services sends an HTTP `POST` request to a configured URL when [specified events](#cs/latest/developer-resources/webhooks/events.html) are triggered.

Webhooks can be used for data synchronization between CKEditor Cloud Services and another system or to build a notifications system. For example, thanks to webhooks, the system might notify the users via email about changes made in the document.

<a id="cs/latest/developer-resources/webhooks/overview.html--benefits-of-using-webhooks">

### Benefits of using webhooks

By using webhooks while integrating your application with the CKEditor Collaboration Server you can make the integration more reliable. Your application will send requests to the CKEditor Collaboration Server only when it is needed, without any periodical requests. It will limit the transfer between both servers and the complexity of implementation, as webhooks are based on REST API endpoints. Webhooks are called almost immediately after specific event occur.

<a id="cs/latest/developer-resources/webhooks/overview.html--examples">

#### Examples

<a id="cs/latest/developer-resources/webhooks/overview.html--synchronization-of-comments">

##### Synchronization of comments

One way of using webhooks can be synchronizing comments with your server. The application can register for [comments-related events](#cs/latest/developer-resources/webhooks/events.html--comments) and add, remove and update comments in a external database according to data included in webhook event’s payloads.

<a id="cs/latest/developer-resources/webhooks/overview.html--comments-notification">

##### Comments notification

Another case where webhooks can be useful is a situation where editors needs to be informed about new comments in a document. Application can register for the `comments.added` webhook event, and after handling it can send email by using any external service providers.

<a id="cs/latest/developer-resources/webhooks/overview.html--saving-document">

##### Saving document

The example of saving document with usage of webhooks and REST API is described in a [Initializing and saving documents](#cs/latest/guides/collaboration/introduction.html--saving-data-with-webhooks) guide.

<a id="cs/latest/developer-resources/webhooks/overview.html--user-access-monitoring">

##### User access monitoring

There may be a need for receiving information who and when connected to the document. It may be easy done with `user.connected` and `user.disconnected` event. Information who, when and for how long accessed the document may be collected by your application.

<a id="cs/latest/developer-resources/webhooks/overview.html--security">

### Security

Every webhook request sent from CKEditor Cloud Services to the configured webhook URL has a signature and a timestamp. Thanks to this, every request received by the server can be checked and confirmed that it comes from CKEditor Cloud Services and has not been modified.

More information about the verification process of signing requests can be found in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide.

<a id="cs/latest/developer-resources/webhooks/overview.html--webhook-order">

### Webhook order

Please keep in mind that webhook events are sent asynchronously. You should, therefore, not rely on the order of the received events.

If operations you are performing are order-sensitive, you should add another layer of verification to your endpoint that handles events.

<a id="cs/latest/developer-resources/webhooks/overview.html--webhook-format">

### Webhook format

Each webhook request sent by CKEditor Cloud Services has the following properties:

* `event` – The name of the event that triggered the webhook.
* `environment_id` – The ID of the environment.
* `sent_at` – The date when the specified webhook was sent.
* `payload` – The payload of the webhook. It contains the data about a specific event.

<a id="cs/latest/developer-resources/webhooks/overview.html--example">

#### Example

Below you can find an example of a sample webhook request sent by CKEditor Cloud Services. It is triggered by a comment added to the comment thread `thread-1` in the document with an ID of `doc-1` by the user with an ID of `user-1`.

```
{
    "event": "comment.added",
    "environment_id": "environment-1",
    "payload": {
        "document": {
            "id": "doc-1"
        },
        "comment": {
            "id": "comment-1",
            "created_at": "2019-05-29T08:17:53.450Z",
            "content": "Some comment content.",
            "thread_id": "thread-1",
            "user": {
                "id": "user-1"
            }
        }
    },
    "sent_at": "2019-05-29T08:17:53.457Z"
}

```

<a id="cs/latest/developer-resources/webhooks/overview.html--example-2">

#### Example

In case of a mechanism, where documents are received through the `collaboration.document.exported` webhook and stored in an external database, the `document.removed_at` field from the payload of the webhook should be compared with a date from a previous event. It will secure application in a case where the order of a received event is changed and the current document will be overridden with an older version from an event which was received after the latest version. If the `document.removed_at` is older than the date already stored in the database, then saving documents should be skipped.

It helps you to avoid inconsistency between states of documents in databases.

<a id="cs/latest/developer-resources/webhooks/overview.html--next-steps">

### Next steps

* Check the [list of events available in CKEditor Cloud Services](#cs/latest/developer-resources/webhooks/events.html).
* Learn how to [manage existing webhooks and create new ones](#cs/latest/developer-resources/webhooks/management.html).

<a id="cs/latest/developer-resources/webhooks/requests.html">source file: "cs/latest/developer-resources/webhooks/requests.html"</a>

## Requests history

In the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises, for each environment, there is a list of sent requests for each created webhook. Each request on the list can be resent and contains some relevant and useful information, such as:

* `request payload`,
* `request headers`,
* `response status`,
* `response body`,
* `response headers`.

The view of a particular request allows you to resent the webhook with exactly the same data, as during the first call.

<a id="cs/latest/developer-resources/webhooks/requests.html--display-requests">

### Display requests

To display a list of requests sent by a particular webhook, you need to display a list of created webhooks for a particular environment.  
Then click the selected webhook from the list.

You will see the paginated list of the webhook’s requests. It comes with basic information like response status, the name of the event which triggered the webhook, and the time when it was sent.

<a id="cs/latest/developer-resources/webhooks/requests.html--filtering-requests">

### Filtering requests

The list of requests usually contains hundreds of requests. To make reviewing them easier, there is a possibility to filter them.

By using the filters above the list you can filter the request by response status, events, and range of time when they ocurred.  
By default, the requests from the last hour are displayed.

<a id="cs/latest/developer-resources/webhooks/requests.html--details-of-request">

### Details of request

To check the details of a particular request click the icon with an arrow on the left side of the selected row.

After selecting a particular request, you will see its details.

You can switch between Request and Response details, by using the `Request` and `Response` tabs at the top.

<a id="cs/latest/developer-resources/webhooks/requests.html--manual-resent">

### Manual resent

In case of failure of a server that receives the webhooks requests, you may need to manually resent a specific request to not lose data.

The request details view allows you to resend the request by using the `Resend request` button.

You will be asked to confirm the action.

After the request will be resent successfully, you see the list of requests with the new request added.

<a id="cs/latest/developer-resources/webhooks/requests.html--next-steps">

### Next steps

* [Read more about testing webhooks in a dedicated article.](#cs/latest/developer-resources/webhooks/testing.html)
* [Check the list of events available in CKEditor Cloud Services.](#cs/latest/developer-resources/webhooks/events.html)

<a id="cs/latest/developer-resources/webhooks/server.html">source file: "cs/latest/developer-resources/webhooks/server.html"</a>

## Webhooks server

To work with incoming webhooks, an application that listens on HTTP `POST` requests sent from CKEditor Cloud Services is needed.

**It is necessary that this application is accessible from the Internet.**

<a id="cs/latest/developer-resources/webhooks/server.html--example">

### Example

Check an [example of a webhooks server implementation in Node.js](#cs/latest/examples/webhooks/webhooks-server-nodejs.html).  
Check an [example of a webhooks server implementation in PHP](#cs/latest/examples/webhooks/webhooks-server-php.html).

<a id="cs/latest/developer-resources/webhooks/testing.html">source file: "cs/latest/developer-resources/webhooks/testing.html"</a>

## Webhooks testing

A crucial part of any integration is testing. To this end, CKEditor Cloud Services provides several tools that facilitate the testing of integration with webhooks.

<a id="cs/latest/developer-resources/webhooks/testing.html--ping-event">

### Ping event

After creating a webhook, CKEditor Cloud Services sends a straightforward `ping` event that can be used to confirm that the integration works correctly.

Payload:

* `id` – The ID of the request.
* `url` – The URL of the request.

<a id="cs/latest/developer-resources/webhooks/testing.html--example">

#### Example

You can find an example of a `ping` event sent by CKEditor Cloud Services below.

```
{
    "event": "ping",
    "environment_id": "environment-1",
    "payload": {
        "id": "id",
        "url": "url",
    },
    "sent_at": "2020-06-15T09:32:17.813Z"
}

```

<a id="cs/latest/developer-resources/webhooks/testing.html--next-steps">

### Next steps

* [Read more about managing webhooks in a dedicated article.](#cs/latest/developer-resources/webhooks/management.html)
* [Read more about the request history in a dedicated article.](#cs/latest/developer-resources/webhooks/requests.html)
* [Check the list of events available in CKEditor Cloud Services.](#cs/latest/developer-resources/webhooks/events.html)

<a id="cs/latest/examples/collaboration-examples/import-export-nodejs.html">source file: "cs/latest/examples/collaboration-examples/import-export-nodejs.html"</a>

## Import and export feature in Node.js

This article presents an example of an application that uses the [import and export feature](#cs/latest/guides/collaboration/import-and-export.html) in Node.js and Express.js.

<a id="cs/latest/examples/collaboration-examples/import-export-nodejs.html--dependencies">

### Dependencies

This example uses the following dependencies:

* `axios`
* `body-parser`
* `cors`
* `express`

It also uses core dependencies from Node.js: `path` and `fs`.

<a id="cs/latest/examples/collaboration-examples/import-export-nodejs.html--example">

### Example

The following example allows you to upload an [editor bundle](#cs/latest/examples/editor-bundle/editor-bundle-nodejs.html), import the document data to CKEditor Cloud Services, and export the collaboration content.

This file presents an example of a simple `Express.js` application.

```
// index.js
const path = require( 'path' );
const fs = require( 'fs' );
const express = require( 'express' );
const axios = require( 'axios' );
const cors = require( 'cors' );
const bodyParser = require( 'body-parser' );
const generateSignature = require( './utils/generateSignature' ); // See: https://ckeditor.com/docs/cs/latest/examples/security/request-signature-nodejs.html.
const editorBundle = fs.readFileSync( path.resolve( '../client/build/ckeditor.js' ) ); // This should be your bundled editor.

const app = express();
const port = 8000; // The default application port.
const bundleVersion = 'bundleVersion'; // This value should be unique per environment.
const apiSecret = 'SECRET'; // Do not forget to hide this value in a safe place e.g. an .env file!
const organizationId = 'organizationId'; // Type your organization ID here.
const environmentId = 'environmentId'; // Type your environment ID here.
// If you use On-Premises application you can adjust baseApiUrl accordingly with your application URL.
const baseApiUrl = `https://${ organizationId }.cke-cs.com/api/v5/${ environmentId }`;

app.use( bodyParser.urlencoded( { extended: true } ) );
app.use( bodyParser.json() );
app.use( cors() );

// This function will be responsible for sending requests to CKEditor Cloud Services API.
async function sendRequest( method, url, body ) {
    const CSTimestamp = Date.now();
    const payload = {
        method,
        url,
        mode: 'no-cors',
        headers: {
            'Content-Type': 'application/json',
            'X-CS-Signature': generateSignature( apiSecret, method, url, CSTimestamp, body ),
            'X-CS-Timestamp': CSTimestamp
        }
    };

    if ( method.toUpperCase() !== 'GET' ) {
        payload.data = body;
    }

    try {
        const { status, data } = await axios( payload );

        return { status, data };
    } catch ( { response } ) {
        const { status, data } = response;

        return { status, data };
    }
}

// Upload the editor bundle. Note that you will need to upload your editor again if you change the bundle.
app.post( '/upload-editor', async ( req, res ) => {
    const { bundleVersion } = req.body;

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/editors`, {
        bundle: editorBundle.toString(),
        config: {
            cloudServices: {
                bundleVersion
            }
        }
    } );

    return res.json( { status, data } );
} );

// Import content to the document.
app.post( '/import', async ( req, res ) => {
    const { documentId, documentContent, bundleVersion } = req.body;

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/collaborations`, {
        document_id: documentId,
        bundle_version: bundleVersion,
        data: documentContent
    } );

    return res.json( { status, data } );
} );

// Export your data from CKEditor Cloud Services. You can schedule export operations e.g. once per hour.
app.get( '/export/:documentId', async ( req, res ) => {
    const { documentId } = req.params;

    const { status, data } = await sendRequest( 'GET', `${ baseApiUrl }/collaborations/${ documentId }` );

    return res.json( { status, data } );
} );

app.listen( port, () => console.log( `The application is listening on port ${ port }!` ) );


```

<a id="cs/latest/examples/collaboration-examples/import-export-nodejs.html--usage">

### Usage

Run:

```
node index.js

```

You can then perform actions and communicate with CKEditor Cloud Services by sending HTTP requests to this application. See the following example:

1. Uploading editor bundle.

```
try {
    const response = await fetch( 'http://localhost:8000/upload-editor', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( { bundleVersion } )
    } );

    const data = await response.json();

    console.log( 'Result of uploading editor:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Importing the collaboration session.

```
try {
    const response = await fetch( 'http://localhost:8000/import', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( { 
            bundleVersion,
            documentId: 'document-1',
            documentContent: '<p>Lorem Ipsum is <b>simply dummy</b> text of the printing and typesetting industry.</p>',
        } )
    } );

    const data = await response.json();

    console.log( 'Result of importing collaborative editing session:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Exporting the collaboration session. The content imported in step 2 should be returned.

```
try {
    const response = await fetch( `http://localhost:8000/export/document-1`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
        }
    } );

    const data = await response.json();

    console.log( 'Result of exporting collaborative editing session:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

<a id="cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html">source file: "cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html"</a>

## Migrating to RTC in Node.js

This article presents an example of an application that allows for migrating users and documents created in non Real-time Collaboration to Real-time Collaboration.

<a id="cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html--dependencies">

### Dependencies

This example uses the following dependencies:

* `axios`
* `body-parser`
* `cors`
* `express`

It also uses core dependencies from Node.js: `path` and `fs`.

<a id="cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html--example">

### Example

The following example allows you to upload an [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html), create a [user](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html) and [import a document to the Real-time Collaboration](#cs/latest/guides/basic-concepts/data-model.html--document).

The following example will cover:

* Uploading an editor bundle to CKEditor Cloud Services
* Creating a Real-time Collaboration user
* Mapping the document and all its data from the non Real-time Collaboration and importing to the CKEditor Cloud Services

Presented below is an example of a simple `Express.js` application.

```
// mapDocumentData.js

/**
 * Maps all data for the document to the structure and assigns data missing in non-RTC
 * according to the CKEditor Cloud Services' requirements.
 *
 * @param {Object} [documentData] The whole data of the document with all its resources saved from the non Real-time Collaboration.
 * @param {String} [documentData.documentId] The ID of the document to import
 * @param {String} [documentData.bundleVersion] The version of the bundled editor to use for the document
 * @param {String} [documentData.editorData] The content of the document in HTML or Markdown
 * @param {Array.<Object>} [documentData.commentThreadsData]
 * @param {Array.<Object>} [documentData.suggestionsData]
 * @param {Array.<Object>} [documentData.revisionsData]
 * @param {String} [suggestionAuthorID] the ID of the user to assign for suggestions that don't have an author assigned to them
 * @returns {Object}
 */
function mapDocumentData( documentData = {}, suggestionAuthorID ) {
    const threads = [];
    const comments = [];

    const {
        commentThreadsData = [],
        suggestionsData = [],
        revisionsData = [],
        documentId,
        bundleVersion,
        editorData
    } = documentData;

    commentThreadsData.forEach( commentThread => {
        const hasMatchingSuggestion = suggestionsData.some( suggestion => suggestion.id === commentThread.id );

        threads.push( {
            id: commentThread.threadId,
            context: commentThread.context,
            resolved_at: commentThread.resolvedAt,
            resolved_by: commentThread.resolvedBy,
            attributes: commentThread.attributes,
            author_id: commentThread.authorId
        } );

        comments.push(
            ...commentThread.comments.map( comment => ( {
                id: comment.commentId,
                thread_id: commentThread.threadId,
                content: comment.content,
                attributes: comment.attributes,
                user: { id: comment.authorId },
                created_at: comment.created_at,
                type: hasMatchingSuggestion ? 2 : 1
            } ) )
        );
    } );

    const revisions = [];
    let version = 1;

    revisionsData.forEach( ( revision, index ) => {
        if ( revision.toVersion > version ) {
            version = revision.toVersion;
        }

        revisions.push( {
            revision_id: revision.id,
            request_id: index,
            name: revision.name,
            creator_id: revision.authorId,
            authors_ids: revision.authors_ids,
            diff_data: JSON.stringify( revision.diffData ),
            created_at: revision.createdAt,
            attributes: revision.attributes,
            from_version: revision.fromVersion,
            to_version: revision.toVersion
        } )
    } );

    const suggestions = suggestionsData.map( suggestion => ( {
        id: suggestion.id,
        type: suggestion.type,
        author_id: suggestion.authorId ?? suggestionAuthorID,
        created_at: suggestion.createdAt,
        has_comments: suggestion.hasComments,
        data: suggestion.data,
        attributes: suggestion.attributes,
    } ) )

    const importBody = {
        id: documentId,
        content: {
            bundle_version: bundleVersion,
            data: editorData,
            version: version ?? undefined
        },
        comments,
        suggestions,
        revisions,
        threads
    };

    return importBody;
}

```

```
// index.js
const path = require( 'path' );
const fs = require( 'fs' );
const express = require( 'express' );
const axios = require( 'axios' );
const cors = require( 'cors' );
const bodyParser = require( 'body-parser' );
const generateSignature = require( './utils/generateSignature' ); // See: https://ckeditor.com/docs/cs/latest/examples/security/request-signature-nodejs.html.
const mapDocumentData = require( './utils/mapDocumentData' );
const editorBundle = fs.readFileSync( path.resolve( '../client/build/ckeditor.js' ) ); // It should be your bundled editor.

const app = express();
const port = 8000; // The default application port.
const apiSecret = 'SECRET'; // Do not forget to hide this value in a safe place e.g. a .env file!
const organizationId = 'organizationId'; // Type your organization ID here.
const environmentId = 'environmentId'; // Type your environment ID here.
// If you use On-Premises application you can adjust baseApiUrl accordingly with your application URL.
const baseApiUrl = `https://${ organizationId }.cke-cs.com/api/v5/${ environmentId }`;

app.use( bodyParser.urlencoded( { extended: true } ) );
app.use( bodyParser.json() );
app.use( cors() );

// This function will be responsible for sending requests to CKEditor Cloud Services API.
async function sendRequest( method, url, body ) {
    const CSTimestamp = Date.now();
    const payload = {
        method,
        url,
        mode: 'no-cors',
        headers: {
            'Content-Type': 'application/json',
            'X-CS-Signature': generateSignature( apiSecret, method, url, CSTimestamp, body ),
            'X-CS-Timestamp': CSTimestamp
        }
    };

    if ( method.toUpperCase() !== 'GET' ) {
        payload.data = body;
    }

    try {
        const { status, data } = await axios( payload );

        return { status, data };
    } catch ( { response } ) {
        const { status, data } = response;

        return { status, data };
    }
}

// Upload the editor bundle. Note that you will need to upload your editor again if you change the bundle.
app.post( '/upload-editor', async ( req, res ) => {
    const { bundleVersion } = req.body;

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/editors`, {
        bundle: editorBundle.toString(),
        config: {
            cloudServices: {
                bundleVersion // This value should be unique per environment.
            }
        }
    } );

    return res.json( { status, data } );
} );

// Create a user for Real-time Collaboration.
app.post( '/create-user', async ( req, res ) => {
    const { email, id, name } = req.body;

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/users`, {
        id,
        email,
        name
    } );

    return res.json( { status, data } );
} );

// Import a document to the CKEditor Cloud Services.
app.post( '/import-document', async ( req, res ) => {
    const {
        documentData,
        suggestionAuthorId
    } = req.body;

    const importBody = mapDocumentData( documentData, suggestionAuthorId );

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/documents`, importBody );

    return res.json( { status, data } );
} );

app.listen( port, () => console.log( `The application is listening on port ${ port }!` ) );

```

<a id="cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html--usage">

### Usage

Run:

```
node index.js

```

By sending HTTP requests to this application you can now perform actions and communicate with CKEditor Cloud Services. See the following example:

1. Uploading editor bundle.

```
try {
    const response = await fetch( 'http://localhost:8000/upload-editor', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( { bundleVersion: '1.0.0' } )
    } );

    const data = await response.json();

    console.log( 'Result of uploading editor:', data );
} catch ( error ) {
    console.log( 'Error occurred when uploading editor:', error );
}

```

1. Creating a user.

```
try {
    const response = await fetch( 'http://localhost:8000/create-user', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( {
            id: 'user-1',
            email: 'example@example.com',
            name: 'Example user'
        } )
    } );

    const data = await response.json();

    console.log( 'Result of uploading user:', data );
} catch ( error ) {
    console.log( 'Error occurred when uploading user:', error );
}

```

1. Importing a document to the CKEditor Cloud Services. For `documentData` you can either use the data taken from your server or you can use the example below.
Click to see the example data. 

```
{
    "documentId": "document-1",
    "bundleVersion": "1.0.0",
    "editorData": "<h2 style=\"text-align:center;\">NON-DISCLOSURE AGREEMENT (NDA)</h2><p>&nbsp;</p><p>This Nondisclosure Agreement or (\"Agreement\") has been entered into on the <suggestion-start name=\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"></suggestion-start>the <suggestion-end name=\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"></suggestion-end>date of 10.05.2021 and is by and between:</p><p><strong>Party Disclosing Information:</strong> James Lahey with a mailing address of <comment-start name=\"eca0c3e71883a578ee37bdc0e510a41a8:49cf1\"></comment-start>3 Maple Rd. Spryfield B3P 1H8<comment-end name=\"eca0c3e71883a578ee37bdc0e510a41a8:49cf1\"></comment-end> &nbsp;(\"Disclosing Party\").</p><p><strong>Party Receiving Information:</strong> &nbsp;Richard Lafleur with a mailing address of &nbsp;1 Bonnyville Dr. Spryfield B3P 1H8 (\"Receiving Party\"). For the purpose of preventing the unauthorized disclosure of Confidential Information as defined below. The parties agree to enter into a confidential relationship concerning the disclosure of certain <suggestion-start name=\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"></suggestion-start>proprietary<suggestion-end name=\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"></suggestion-end><suggestion-start name=\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"></suggestion-start>business<suggestion-end name=\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"></suggestion-end> property and confidential information (\"Confidential Information\").</p><p>&nbsp;</p><h2>1. Definition of Confidential Information</h2><p>For purposes of this Agreement, \"Confidential Information\" shall include all information or material that has or could have commercial value or other utility in the business in which the Disclosing Party is engaged. If Confidential Information is in written form, the Disclosing Party shall label or stamp the materials with the word \"Confidential\" or some similar warning. If Confidential Information is transmitted orally, the Disclosing Party shall promptly provide a writing indicating that such oral communication constituted Confidential Information.</p><h2>2. Exclusions from Confidential Information</h2><p>Receiving Party's obligations under this Agreement do not extend to information that is:(a) publicly known at the time of disclosure or subsequently becomes publicly known through no fault of the Receiving Party; (b) discovered or created by the Receiving Party before disclosure by Disclosing Party; (c) learned by the Receiving Party through legitimate means other than from the Disclosing Party or Disclosing Party's representatives; or (d) is disclosed by Receiving Party with Disclosing Party's prior written approval.</p><h2>3. Obligations of Receiving Party</h2><p>Receiving Party shall hold and maintain the Confidential Information in strictest confidence for the sole and exclusive benefit of the Disclosing Party. Receiving Party shall carefully restrict access to Confidential Information to employees, contractors and third parties as is reasonably required and shall require those persons to sign nondisclosure restrictions at least as protective as those in this Agreement. Receiving Party shall not, without the prior written approval of Disclosing Party, use for Receiving Party's benefit, publish, copy, or otherwise disclose to others, or permit the use by others for their benefit or to the detriment of Disclosing Party, any Confidential Information. Receiving Party shall return to Disclosing Party any and all records, notes, and other written, printed, or tangible materials in its possession pertaining to Confidential Information immediately if Disclosing Party requests it in writing.</p><h2>4. Time Periods</h2><p>The nondisclosure provisions of this Agreement shall survive the termination of this Agreement and Receiving Party's duty to hold Confidential Information in confidence shall remain in effect until the Confidential Information no longer qualifies as a trade secret or until Disclosing Party sends Receiving Party written notice releasing Receiving Party from this Agreement, whichever occurs first.</p><h2>5. Relationships</h2><p>Nothing contained in this Agreement shall be deemed to constitute either party a partner, joint venture or employee of the other party for any purpose.</p><h2>6. Severability</h2><p>If a court finds any provision of this Agreement invalid or unenforceable, the remainder of this Agreement shall be interpreted so as best to affect the intent of the parties.</p><h2>7. Integration</h2><p>This Agreement expresses the complete understanding of the parties with respect to the subject matter and supersedes all prior proposals, agreements, representations, and understandings. This Agreement may not be amended except in writing signed by both parties.</p><h2>8. Waiver</h2><p>The failure to exercise any right provided in this Agreement shall not be a waiver of prior or subsequent rights.</p><h2>9. Notice of Immunity</h2><p>Employee is provided notice that an individual shall not be held criminally or civilly liable under any federal or state trade secret law for the disclosure of a trade secret that is made <comment-start name=\"e5964fb81e95e0cd712ecf95fafad425f:57cf0\"></comment-start>(i)<comment-end name=\"e5964fb81e95e0cd712ecf95fafad425f:57cf0\"></comment-end> in confidence to a federal, state, or local government official, either directly or indirectly, or to an attorney; and (ii) solely for the purpose of reporting or investigating a suspected violation of law; or is made in a complaint or other document filed in a lawsuit or other proceeding, if such filing is made under seal. An individual who files a lawsuit for retaliation by an employer for reporting a suspected violation of law may disclose the trade secret to the attorney of the individual and use the trade secret information in the court proceeding, if the individual (i) files any document containing the trade secret under seal; and (ii) does not disclose the trade secret, except pursuant to court order. This Agreement and each party's obligations shall be binding on the representatives, assigns and successors of such party. Each party has signed this Agreement through its authorized representative.</p><p>&nbsp;</p><p>&nbsp;</p><p><strong>DISCLOSING PARTY Signature:</strong> _____________________________________________________</p><p><strong>Typed or Printed Name:</strong> James Lahey</p><p><strong>Date:</strong> 10.05.2021</p><p>&nbsp;</p><p><strong>RECEIVING PARTY Signature:</strong> _____________________________________________________</p><p><strong>Typed or Printed Name:</strong> Richard Lafleur</p><p><strong>Date:</strong> 10.05.2021</p>",
    "commentThreadsData": [
        {
            "threadId": "eca0c3e71883a578ee37bdc0e510a41a8",
            "context": {
            "type": "text",
            "value": "3 Maple Rd. Spryfield B3P 1H8"
            },
            "authorId": "user-1",
            "resolvedAt": null,
            "resolvedBy": null,
            "comments": [
                {
                    "commentId": "e949f2f153f07ddc9b5f161062d4a1ad9",
                    "content": "<p>This might be Mr. Lafleur's address. Can we double-check the addresses?</p>",
                    "createdAt": "2023-08-24T09:35:17.338Z",
                    "authorId": "user-1",
                    "attributes": {}
                }
            ],
            "attributes": {}
        },
        {
            "threadId": "e5964fb81e95e0cd712ecf95fafad425f",
            "context": {
            "type": "text",
            "value": "(i)"
            },
            "authorId": "user-1",
            "resolvedAt": null,
            "resolvedBy": null,
            "comments": [
                {
                    "commentId": "edadb356033be84bb93085092e4d8b15b",
                    "content": "<p>Maybe we should change this listing to be consistent with the one from section 2</p>",
                    "createdAt": "2023-08-24T09:37:11.805Z",
                    "authorId": "user-1",
                    "attributes": {}
                }
            ],
            "attributes": {}
        }
    ],
    "suggestionsData": [
        {
            "id": "ea6c5028e3c0efaf0b9a23d227d89696c",
            "type": "deletion",
            "createdAt": "2023-08-24T09:31:40.515Z",
            "hasComments": false,
            "data": null,
            "attributes": {}
        },
        {
            "id": "e513f8e2e4eca79825823ff00294f3716",
            "type": "deletion",
            "createdAt": "2023-08-24T09:32:02.186Z",
            "hasComments": false,
            "data": null,
            "attributes": {}
        },
        {
            "id": "e64910f0cd32232aac1cce1c6b5b565b6",
            "type": "insertion",
            "createdAt": "2023-08-24T09:32:02.186Z",
            "hasComments": false,
            "data": null,
            "attributes": {}
        }
    ],
    "revisionsData": [
        {
            "id": "initial",
            "name": "Empty document",
            "creatorId": "user-1",
            "authorsIds": [],
            "diffData": {
                "main": {
                    "insertions": "[{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]}]",
                    "deletions": "[{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]}]",
                    "attachChange": null,
                    "attributesBefore": {},
                    "attributesAfter": {}
                }
            },
            "createdAt": "2023-08-24T09:28:43.499Z",
            "attributes": {},
            "fromVersion": 2,
            "toVersion": 2
        },
        {
            "id": "ed433b9857b18e2ece0ca0b19a0288ba5",
            "name": "revision-1",
            "creatorId": "user-1",
            "authorsIds": [
            "user-1"
            ],
            "diffData": {
                "main": {
                    "insertions": "[{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[[\"data-revision-start-before\",\"insertion:user-1:0\"],[\"style\",\"text-align:center;\"]],\"children\":[\"NON-DISCLOSURE AGREEMENT (NDA)\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Nondisclosure Agreement or (\\\"Agreement\\\") has been entered into on the \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"the \",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"date of 10.05.2021 and is by and between:\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Disclosing Information:\"]},\" James Lahey with a mailing address of 3 Maple Rd. Spryfield B3P 1H8    (\\\"Disclosing Party\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Receiving Information:\"]},\"    Richard Lafleur with a mailing address of    1 Bonnyville Dr. Spryfield B3P 1H8 (\\\"Receiving Party\\\"). For the purpose of preventing the unauthorized disclosure of Confidential Information as defined below. The parties agree to enter into a confidential relationship concerning the disclosure of certain \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},\"proprietary\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\"business\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\" property and confidential information (\\\"Confidential Information\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"1. Definition of Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"For purposes of this Agreement, \\\"Confidential Information\\\" shall include all information or material that has or could have commercial value or other utility in the business in which the Disclosing Party is engaged. If Confidential Information is in written form, the Disclosing Party shall label or stamp the materials with the word \\\"Confidential\\\" or some similar warning. If Confidential Information is transmitted orally, the Disclosing Party shall promptly provide a writing indicating that such oral communication constituted Confidential Information.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"2. Exclusions from Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party's obligations under this Agreement do not extend to information that is:(a) publicly known at the time of disclosure or subsequently becomes publicly known through no fault of the Receiving Party; (b) discovered or created by the Receiving Party before disclosure by Disclosing Party; (c) learned by the Receiving Party through legitimate means other than from the Disclosing Party or Disclosing Party's representatives; or (d) is disclosed by Receiving Party with Disclosing Party's prior written approval.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"3. Obligations of Receiving Party\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party shall hold and maintain the Confidential Information in strictest confidence for the sole and exclusive benefit of the Disclosing Party. Receiving Party shall carefully restrict access to Confidential Information to employees, contractors and third parties as is reasonably required and shall require those persons to sign nondisclosure restrictions at least as protective as those in this Agreement. Receiving Party shall not, without the prior written approval of Disclosing Party, use for Receiving Party's benefit, publish, copy, or otherwise disclose to others, or permit the use by others for their benefit or to the detriment of Disclosing Party, any Confidential Information. Receiving Party shall return to Disclosing Party any and all records, notes, and other written, printed, or tangible materials in its possession pertaining to Confidential Information immediately if Disclosing Party requests it in writing.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"4. Time Periods\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The nondisclosure provisions of this Agreement shall survive the termination of this Agreement and Receiving Party's duty to hold Confidential Information in confidence shall remain in effect until the Confidential Information no longer qualifies as a trade secret or until Disclosing Party sends Receiving Party written notice releasing Receiving Party from this Agreement, whichever occurs first.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"5. Relationships\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Nothing contained in this Agreement shall be deemed to constitute either party a partner, joint venture or employee of the other party for any purpose.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"6. Severability\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"If a court finds any provision of this Agreement invalid or unenforceable, the remainder of this Agreement shall be interpreted so as best to affect the intent of the parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"7. Integration\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Agreement expresses the complete understanding of the parties with respect to the subject matter and supersedes all prior proposals, agreements, representations, and understandings. This Agreement may not be amended except in writing signed by both parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"8. Waiver\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The failure to exercise any right provided in this Agreement shall not be a waiver of prior or subsequent rights.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"9. Notice of Immunity\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Employee is provided notice that an individual shall not be held criminally or civilly liable under any federal or state trade secret law for the disclosure of a trade secret that is made (i) in confidence to a federal, state, or local government official, either directly or indirectly, or to an attorney; and (ii) solely for the purpose of reporting or investigating a suspected violation of law; or is made in a complaint or other document filed in a lawsuit or other proceeding, if such filing is made under seal. An individual who files a lawsuit for retaliation by an employer for reporting a suspected violation of law may disclose the trade secret to the attorney of the individual and use the trade secret information in the court proceeding, if the individual (i) files any document containing the trade secret under seal; and (ii) does not disclose the trade secret, except pursuant to court order. This Agreement and each party's obligations shall be binding on the representatives, assigns and successors of such party. Each party has signed this Agreement through its authorized representative.\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"DISCLOSING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" James Lahey\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"RECEIVING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" Richard Lafleur\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[[\"data-revision-end-after\",\"insertion:user-1:0\"]],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]}]",
                    "deletions": "[{\"type\":\"c\",\"name\":\"p\",\"attributes\":[[\"data-revision-end-after\",\"deletion:user-1:0\"],[\"data-revision-start-before\",\"deletion:user-1:0\"]],\"children\":[]}]",
                    "attachChange": null,
                    "attributesBefore": {},
                    "attributesAfter": {}
                }
            },
            "createdAt": "2023-08-24T09:33:51.568Z",
            "attributes": {},
            "fromVersion": 2,
            "toVersion": 14
        },
        {
            "id": "e6a32e19aceae7a67bb9861a0b887611b",
            "name": "",
            "creatorId": null,
            "authorsIds": [
            "user-1"
            ],
            "diffData": {
                "main": {
                    "insertions": "[{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[[\"style\",\"text-align:center;\"]],\"children\":[\"NON-DISCLOSURE AGREEMENT (NDA)\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Nondisclosure Agreement or (\\\"Agreement\\\") has been entered into on the \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"the \",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"date of 10.05.2021 and is by and between:\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Disclosing Information:\"]},\" James Lahey with a mailing address of \",{\"type\":\"u\",\"name\":\"comment-start\",\"attributes\":[[\"name\",\"eca0c3e71883a578ee37bdc0e510a41a8:49cf1\"]],\"children\":[]},\"3 Maple Rd. Spryfield B3P 1H8\",{\"type\":\"u\",\"name\":\"comment-end\",\"attributes\":[[\"name\",\"eca0c3e71883a578ee37bdc0e510a41a8:49cf1\"]],\"children\":[]},\"    (\\\"Disclosing Party\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Receiving Information:\"]},\"    Richard Lafleur with a mailing address of    1 Bonnyville Dr. Spryfield B3P 1H8 (\\\"Receiving Party\\\"). For the purpose of preventing the unauthorized disclosure of Confidential Information as defined below. The parties agree to enter into a confidential relationship concerning the disclosure of certain \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},\"proprietary\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\"business\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\" property and confidential information (\\\"Confidential Information\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"1. Definition of Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"For purposes of this Agreement, \\\"Confidential Information\\\" shall include all information or material that has or could have commercial value or other utility in the business in which the Disclosing Party is engaged. If Confidential Information is in written form, the Disclosing Party shall label or stamp the materials with the word \\\"Confidential\\\" or some similar warning. If Confidential Information is transmitted orally, the Disclosing Party shall promptly provide a writing indicating that such oral communication constituted Confidential Information.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"2. Exclusions from Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party's obligations under this Agreement do not extend to information that is:(a) publicly known at the time of disclosure or subsequently becomes publicly known through no fault of the Receiving Party; (b) discovered or created by the Receiving Party before disclosure by Disclosing Party; (c) learned by the Receiving Party through legitimate means other than from the Disclosing Party or Disclosing Party's representatives; or (d) is disclosed by Receiving Party with Disclosing Party's prior written approval.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"3. Obligations of Receiving Party\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party shall hold and maintain the Confidential Information in strictest confidence for the sole and exclusive benefit of the Disclosing Party. Receiving Party shall carefully restrict access to Confidential Information to employees, contractors and third parties as is reasonably required and shall require those persons to sign nondisclosure restrictions at least as protective as those in this Agreement. Receiving Party shall not, without the prior written approval of Disclosing Party, use for Receiving Party's benefit, publish, copy, or otherwise disclose to others, or permit the use by others for their benefit or to the detriment of Disclosing Party, any Confidential Information. Receiving Party shall return to Disclosing Party any and all records, notes, and other written, printed, or tangible materials in its possession pertaining to Confidential Information immediately if Disclosing Party requests it in writing.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"4. Time Periods\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The nondisclosure provisions of this Agreement shall survive the termination of this Agreement and Receiving Party's duty to hold Confidential Information in confidence shall remain in effect until the Confidential Information no longer qualifies as a trade secret or until Disclosing Party sends Receiving Party written notice releasing Receiving Party from this Agreement, whichever occurs first.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"5. Relationships\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Nothing contained in this Agreement shall be deemed to constitute either party a partner, joint venture or employee of the other party for any purpose.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"6. Severability\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"If a court finds any provision of this Agreement invalid or unenforceable, the remainder of this Agreement shall be interpreted so as best to affect the intent of the parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"7. Integration\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Agreement expresses the complete understanding of the parties with respect to the subject matter and supersedes all prior proposals, agreements, representations, and understandings. This Agreement may not be amended except in writing signed by both parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"8. Waiver\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The failure to exercise any right provided in this Agreement shall not be a waiver of prior or subsequent rights.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"9. Notice of Immunity\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Employee is provided notice that an individual shall not be held criminally or civilly liable under any federal or state trade secret law for the disclosure of a trade secret that is made \",{\"type\":\"u\",\"name\":\"comment-start\",\"attributes\":[[\"name\",\"e5964fb81e95e0cd712ecf95fafad425f:57cf0\"]],\"children\":[]},\"(i)\",{\"type\":\"u\",\"name\":\"comment-end\",\"attributes\":[[\"name\",\"e5964fb81e95e0cd712ecf95fafad425f:57cf0\"]],\"children\":[]},\" in confidence to a federal, state, or local government official, either directly or indirectly, or to an attorney; and (ii) solely for the purpose of reporting or investigating a suspected violation of law; or is made in a complaint or other document filed in a lawsuit or other proceeding, if such filing is made under seal. An individual who files a lawsuit for retaliation by an employer for reporting a suspected violation of law may disclose the trade secret to the attorney of the individual and use the trade secret information in the court proceeding, if the individual (i) files any document containing the trade secret under seal; and (ii) does not disclose the trade secret, except pursuant to court order. This Agreement and each party's obligations shall be binding on the representatives, assigns and successors of such party. Each party has signed this Agreement through its authorized representative.\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"DISCLOSING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" James Lahey\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"RECEIVING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" Richard Lafleur\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]}]",
                    "deletions": "[{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[[\"style\",\"text-align:center;\"]],\"children\":[\"NON-DISCLOSURE AGREEMENT (NDA)\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Nondisclosure Agreement or (\\\"Agreement\\\") has been entered into on the \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"the \",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:ea6c5028e3c0efaf0b9a23d227d89696c:user-1\"]],\"children\":[]},\"date of 10.05.2021 and is by and between:\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Disclosing Information:\"]},\" James Lahey with a mailing address of 3 Maple Rd. Spryfield B3P 1H8    (\\\"Disclosing Party\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Party Receiving Information:\"]},\"    Richard Lafleur with a mailing address of    1 Bonnyville Dr. Spryfield B3P 1H8 (\\\"Receiving Party\\\"). For the purpose of preventing the unauthorized disclosure of Confidential Information as defined below. The parties agree to enter into a confidential relationship concerning the disclosure of certain \",{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},\"proprietary\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"insertion:e64910f0cd32232aac1cce1c6b5b565b6:user-1\"]],\"children\":[]},{\"type\":\"u\",\"name\":\"suggestion-start\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\"business\",{\"type\":\"u\",\"name\":\"suggestion-end\",\"attributes\":[[\"name\",\"deletion:e513f8e2e4eca79825823ff00294f3716:user-1\"]],\"children\":[]},\" property and confidential information (\\\"Confidential Information\\\").\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"1. Definition of Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"For purposes of this Agreement, \\\"Confidential Information\\\" shall include all information or material that has or could have commercial value or other utility in the business in which the Disclosing Party is engaged. If Confidential Information is in written form, the Disclosing Party shall label or stamp the materials with the word \\\"Confidential\\\" or some similar warning. If Confidential Information is transmitted orally, the Disclosing Party shall promptly provide a writing indicating that such oral communication constituted Confidential Information.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"2. Exclusions from Confidential Information\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party's obligations under this Agreement do not extend to information that is:(a) publicly known at the time of disclosure or subsequently becomes publicly known through no fault of the Receiving Party; (b) discovered or created by the Receiving Party before disclosure by Disclosing Party; (c) learned by the Receiving Party through legitimate means other than from the Disclosing Party or Disclosing Party's representatives; or (d) is disclosed by Receiving Party with Disclosing Party's prior written approval.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"3. Obligations of Receiving Party\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Receiving Party shall hold and maintain the Confidential Information in strictest confidence for the sole and exclusive benefit of the Disclosing Party. Receiving Party shall carefully restrict access to Confidential Information to employees, contractors and third parties as is reasonably required and shall require those persons to sign nondisclosure restrictions at least as protective as those in this Agreement. Receiving Party shall not, without the prior written approval of Disclosing Party, use for Receiving Party's benefit, publish, copy, or otherwise disclose to others, or permit the use by others for their benefit or to the detriment of Disclosing Party, any Confidential Information. Receiving Party shall return to Disclosing Party any and all records, notes, and other written, printed, or tangible materials in its possession pertaining to Confidential Information immediately if Disclosing Party requests it in writing.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"4. Time Periods\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The nondisclosure provisions of this Agreement shall survive the termination of this Agreement and Receiving Party's duty to hold Confidential Information in confidence shall remain in effect until the Confidential Information no longer qualifies as a trade secret or until Disclosing Party sends Receiving Party written notice releasing Receiving Party from this Agreement, whichever occurs first.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"5. Relationships\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Nothing contained in this Agreement shall be deemed to constitute either party a partner, joint venture or employee of the other party for any purpose.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"6. Severability\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"If a court finds any provision of this Agreement invalid or unenforceable, the remainder of this Agreement shall be interpreted so as best to affect the intent of the parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"7. Integration\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"This Agreement expresses the complete understanding of the parties with respect to the subject matter and supersedes all prior proposals, agreements, representations, and understandings. This Agreement may not be amended except in writing signed by both parties.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"8. Waiver\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"The failure to exercise any right provided in this Agreement shall not be a waiver of prior or subsequent rights.\"]},{\"type\":\"c\",\"name\":\"h2\",\"attributes\":[],\"children\":[\"9. Notice of Immunity\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[\"Employee is provided notice that an individual shall not be held criminally or civilly liable under any federal or state trade secret law for the disclosure of a trade secret that is made (i) in confidence to a federal, state, or local government official, either directly or indirectly, or to an attorney; and (ii) solely for the purpose of reporting or investigating a suspected violation of law; or is made in a complaint or other document filed in a lawsuit or other proceeding, if such filing is made under seal. An individual who files a lawsuit for retaliation by an employer for reporting a suspected violation of law may disclose the trade secret to the attorney of the individual and use the trade secret information in the court proceeding, if the individual (i) files any document containing the trade secret under seal; and (ii) does not disclose the trade secret, except pursuant to court order. This Agreement and each party's obligations shall be binding on the representatives, assigns and successors of such party. Each party has signed this Agreement through its authorized representative.\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"DISCLOSING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" James Lahey\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"RECEIVING PARTY Signature:\"]},\" _____________________________________________________\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Typed or Printed Name:\"]},\" Richard Lafleur\"]},{\"type\":\"c\",\"name\":\"p\",\"attributes\":[],\"children\":[{\"type\":\"a\",\"name\":\"strong\",\"attributes\":[],\"children\":[\"Date:\"]},\" 10.05.2021\"]}]",
                    "attachChange": null,
                    "attributesBefore": {},
                    "attributesAfter": {}
                }
            },
            "createdAt": "2023-08-24T09:37:39.710Z",
            "attributes": {},
            "fromVersion": 14,
            "toVersion": 16
        }
    ]
}


```

```
try {
    const response = await fetch( 'http://localhost:8000/import-document', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( {
            documentData,
            suggestionAuthorId: 'user-1'
        } )
    } );

    const data = await response.json();

    console.log( 'Result of importing the document:', data );
} catch ( error ) {
    console.log( 'Error occurred during importing the document:', error );
}

```

<a id="cs/latest/examples/collaboration-examples/storage-feature-nodejs.html">source file: "cs/latest/examples/collaboration-examples/storage-feature-nodejs.html"</a>

## Document storage feature in Node.js

This article presents an example of an application that uses the [document storage feature](#cs/latest/guides/collaboration/document-storage.html) in Node.js and Express.js.

This example assumes that the Document Storage feature is already properly enabled. To learn how to enable document storage refer to our [dedicated guide](#cs/latest/guides/collaboration/document-storage.html--enabling-the-document-storage-feature).

<a id="cs/latest/examples/collaboration-examples/storage-feature-nodejs.html--dependencies">

### Dependencies

This example uses the following dependencies:

* `axios`
* `body-parser`
* `cors`
* `express`

It also uses core dependencies from Node.js: `path` and `fs`.

<a id="cs/latest/examples/collaboration-examples/storage-feature-nodejs.html--example">

### Example

The following example allows you to upload an [editor bundle](#cs/latest/examples/editor-bundle/editor-bundle-nodejs.html), import a document to the storage, get a list of documents, get a document, and remove a document.

This file presents an example of a simple Express.js application.

```
// index.js
const path = require( 'path' );
const fs = require( 'fs' );
const express = require( 'express' );
const axios = require( 'axios' );
const cors = require( 'cors' );
const bodyParser = require( 'body-parser' );
const generateSignature = require( './utils/generateSignature' ); // See: https://ckeditor.com/docs/cs/latest/examples/security/request-signature-nodejs.html.
const editorBundle = fs.readFileSync( path.resolve( '../client/build/ckeditor.js' ) ); // It should be your bundled editor.

const app = express();
const port = 8000; // The default application port.
const apiSecret = 'SECRET'; // Do not forget to hide this value in a safe place e.g. a .env file!
const organizationId = 'organizationId'; // Type your organization ID here.
const environmentId = 'environmentId'; // Type your environment ID here.
// If you use On-Premises application you can adjust baseApiUrl accordingly with your application URL.
const baseApiUrl = `https://${ organizationId }.cke-cs.com/api/v5/${ environmentId }`;

app.use( bodyParser.urlencoded( { extended: true } ) );
app.use( bodyParser.json() );
app.use( cors() );

// This function will be responsible for sending requests to CKEditor Cloud Services API.
async function sendRequest( method, url, body ) {
    const CSTimestamp = Date.now();
    const payload = {
        method,
        url,
        mode: 'no-cors',
        headers: {
            'Content-Type': 'application/json',
            'X-CS-Signature': generateSignature( apiSecret, method, url, CSTimestamp, body ),
            'X-CS-Timestamp': CSTimestamp
        }
    };

    if ( method.toUpperCase() !== 'GET' ) {
        payload.data = body;
    }

    try {
        const { status, data } = await axios( payload );

        return { status, data };
    } catch ( { response } ) {
        const { status, data } = response;

        return { status, data };
    }
}

// Upload the editor bundle. Note that you will need to upload your editor again if you change the bundle.
app.post( '/upload-editor', async ( req, res ) => {
    const { bundleVersion } = req.body;

    const { status, data } = await sendRequest( 'POST', `${ baseApiUrl }/editors`, {
        bundle: editorBundle.toString(),
        config: {
            cloudServices: {
                bundleVersion // This value should be unique per environment.
            }
        }
    } );

    return res.json( { status, data } );
} );

// Synchronously imports the document to the storage
app.post( '/storage', async ( req, res ) => {
    const { documentId, documentContent } = req.body;

    const { status, data } = await sendRequest( 
        'POST', 
        `${ baseApiUrl }/storage`,
        {
            document_id: documentId,
            data: documentContent
        }
    );

    return res.json( { status, data } );
} );

// Deletes a single document from the storage.
app.delete( '/storage/:documentId', async ( req, res ) => {
    const { documentId } = req.params;

    const { status } = await sendRequest( 'DELETE', `${ baseApiUrl }/storage/${ documentId }` );

    return res.json( { status } );
} );

// Gets a single document.
app.get( '/storage/:documentId', async ( req, res ) => {
    const { documentId } = req.params;

    const { status, data } = await sendRequest( 'GET', `${ baseApiUrl }/storage/${ documentId }` );

    return res.json( { status, data } );
} );

// Gets a list of documents.
app.get( '/storage', async ( req, res ) => {
    const { status, data } = await sendRequest( 'GET', `${ baseApiUrl }/storage` );

    return res.json( { status, data } );
} );

app.listen( port, () => console.log( `The application is listening on port ${ port }!` ) );

```

<a id="cs/latest/examples/collaboration-examples/storage-feature-nodejs.html--usage">

### Usage

Run:

```
node index.js

```

By sending HTTP requests to this application you can now perform actions and communicate with CKEditor Cloud Services. See the following example:

1. Upload an editor bundle.

```
try {
    const response = await fetch( 'http://localhost:8000/upload-editor', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( { bundleVersion: '1.0.0' } )
    } );

    const data = await response.json();

    console.log( 'Result of uploading editor:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Synchronously import the document to the storage

```
try {
    const response = await fetch( 'http://localhost:8000/storage', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify( { 
            documentId: "document-1",
            documentContent: "<p>Lorem Ipsum is <b>simply dummy</b> text of the printing and typesetting industry.</p>",
        } )
    } );

    const data = await response.json();

    console.log( 'Result of inserting document:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Get a list of documents – an array with the newly created `document-1` should be returned under the `data` property.

```
try {
    const response = await fetch( `http://localhost:8000/storage`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
        }
    } );

    const data = await response.json();

    console.log( 'Result of getting documents:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Get the document with the `document-1` ID. The content returned should be equal to the content imported in step 2.

```
try {
    const response = await fetch( `http://localhost:8000/storage/document-1`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
        }
    } );

    const data = await response.json();

    console.log( 'Result of getting document:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Delete the document with the `document-1` ID.

```
try {
    const response = await fetch( `http://localhost:8000/storage/document-1`, {
        method: 'DELETE',
        headers: {
            'Content-Type': 'application/json'
        }
    } );

    const data = await response.json();

    console.log( 'Result of deleting document:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

1. Try to get the document with the `document-1` ID again. An error will be thrown explaining that the document does not exist.

```
try {
    const response = await fetch( `http://localhost:8000/storage/document-1`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
        }
    } );

    const data = await response.json();

    console.log( 'Result of getting document:', data );
} catch ( error ) {
    console.log( 'Error occurred:', error );
}

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html">source file: "cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html"</a>

## Advanced editor bundling in Node.js

This article presents how to create a CKEditor 5 [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) in Node.js. It is a step-by-step guide on creating an editor bundle from the CKEditor 5 package downloaded from [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/), but can be easily adapted for a variety of setups. An editor bundle is required by CKEditor Cloud Services to enable [document storage](#cs/latest/guides/collaboration/document-storage.html), [import and export](#cs/latest/guides/collaboration/import-and-export.html) as well as [connection optimization](#cs/latest/guides/collaboration/connection-optimization.html) features.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--bundle-requirements">

### Bundle requirements

The editor bundle that can be used by CKEditor Cloud Services must fulfill certain requirements:

* It needs to be built into a single `.js` file.
* The plugins should be added in the [builtinPlugins](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditor-Editor.html#static-member-builtinPlugins) property to be included in the editor bundle. You cannot use the [config.plugins](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-plugins) option for adding the plugins to the editor.
* The `output.library` property in the webpack configuration should be set to`CKEditorCS` value.
* Plugins used in the editor bundle cannot execute external HTTP requests.
* The editor instance needs to be a default export in the editor bundle.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--creating-a-bundle">

### Creating a bundle

The following example acts as a template for how to prepare an editor bundle configuration. It assumes that you have basic CKEditor 5 files - the `package.json`, `main.js`, `index.html` and `style.css` files which are the result of using [CKEditor 5 Builder](https://ckeditor.com/ckeditor-5/builder/) with “Self-hosted (npm)” integration method.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--dependencies">

#### Dependencies

This example uses the following dependencies:

* `ckeditor5`
* `ckeditor5-premium-features`
* `webpack`
* `webpack-cli`
* `mini-css-extract-plugin`

If you followed the Builder setup, `ckeditor5*` packages should be already there. For the rest run:

```
npm install -D webpack webpack-cli mini-css-extract-plugin

```

After that, your `package.json` dependencies sections should look as below:

```
{
  "dependencies": {
    "ckeditor5": "^42.0.0",
    "ckeditor5-premium-features": "^42.0.0"
  },
  "devDependencies": {
    "mini-css-extract-plugin": "^2.9.0",
    "webpack": "^5.92.1",
    "webpack-cli": "^5.1.4"
  }
}

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--editor-setup">

#### Editor setup

It is highly recommended to use the same editor setup for both creating a bundle and integrating CKEditor 5 with the frontend layer. This way, it is easier to keep everything synchronized and consistent between the front end and back end. This requires slight adjustments to the above setup in how parts of the editor are defined and used.

The common parts for both setups are the editor class, list of plugins and editor config. We will split the `main.js` file into 3 files:

* The `main.js` file that will define shared parts.
* The `main-fe.js` file, that will be responsible for editor setup in the frontend application.
* The `main-be.js` file, from which the editor bundle will be generated. It will be bundler entry file.

The first step is adjusting the `main.js` file.

```
// main.js

import {
    ClassicEditor,
    Essentials,
    Paragraph,
    Bold,
    Italic
} from 'ckeditor5';

import {
    RealTimeCollaborativeEditing
} from 'ckeditor5-premium-features';

// 1. Remove style imports. Those will be used in main-fe.js.
// import 'ckeditor5/ckeditor5.css';
// import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

// import './style.css';

// 2. Create a list of plugins which will be exported.
const pluginList = [
    Essentials,
    Paragraph,
    Bold,
    Italic,
    RealTimeCollaborativeEditing
];

// 3. Adjust 'editorConfig' to utilize 'pluginList'.
const editorConfig = {
    plugins: pluginList,
    ...
}

// 4. Export shared parts, instead of initializing editor.
// ClassicEditor.create(document.querySelector('#editor'), editorConfig);

export {
    ClassicEditor,
    pluginList,
    editorConfig
}

```

Next, we will create `main-fe.js` which will be used on the front end.

```
// main-fe.js

import { ClassicEditor, editorConfig } from './main.js';

// 1. Move style imports from main.js here.
import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';

import './style.css';

// 2. Initialize editor.
ClassicEditor.create(document.querySelector('#editor'), editorConfig);

```

After that, `main-be.js` file, used for bundling, should be created.

```
// main-be.js

import { ClassicEditor, pluginList } from './main.js';

class CKEditorCS extends ClassicEditor {}

// 1. Assign plugins to be used in bundle.
CKEditorCS.builtinPlugins = pluginList;

// 2. Export editor class.
export default CKEditorCS;

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--frontend-building">

#### Frontend building

With the above changes, your application can be build and bundled the same way as before. The only adjustment needed is changing the file which is imported.

```
<!doctype html>
<html lang="en">
    <head>...</head>
    <body>
        ...
        <!-- <script type="module" src="./main.js"></script> -->
        <script type="module" src="./main-fe.js"></script>
    </body>
</html>

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--bundler-configuration">

#### Bundler configuration

Next, you need to prepare [webpack](https://webpack.js.org/) configuration to generate a valid bundle.

```
const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' );

module.exports = {
    entry: './main-be.js', // Your editor build configuration.
    output: {
        filename: 'editor.bundle.js', // Content of this file is required to upload to CKEditor Cloud Services.
        library: 'CKEditorCS', // It is required to expose you editor class under the "CKEditorCS" name!

        libraryTarget: 'umd',
        libraryExport: 'default',
        clean: true
    },
    plugins: [
        new MiniCssExtractPlugin()
    ],
    module: {
        parser: {
            javascript: {
                dynamicImportMode: 'eager'
            }
        },
        rules: [
            {
                test: /\.css$/i,
                use: [MiniCssExtractPlugin.loader, 'css-loader']
            }
        ]
    },
    performance: { hints: false }
};

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--generating-the-bundle">

#### Generating the bundle

Then, run the following commands inside the CKEditor 5 package folder:

```
npx webpack --mode production

```

This command will result in the generation of the `./dist/editor.bundle.js` file. This is the bundle file which then should be [uploaded to CKEditor Cloud Services server](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle).

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--building-the-editor-bundle-with-typescript">

#### Building the editor bundle with TypeScript

The examples presented above are using JavaScript in the editor source files. Building the editor bundle with TypeScript is also possible. To start using TypeScript, follow these steps:

1. Integrate TypeScript with webpack. Refer to [this guide](https://webpack.js.org/guides/typescript/) for more details.
2. Change the extension of the editor source file to `.ts`. Adjust the entry path in `webpack.config.js`.
3. Refer to the [Working with TypeScript](https://ckeditor.com/docs/ckeditor5/latest/getting-started/setup/typescript-support.html) guide and adjust the imports and configuration settings if needed.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--creating-a-bundle-from-legacy-configuration">

### Creating a bundle from legacy configuration

The following example acts as a template for how to prepare an editor build and bundler configuration. It assumes that you have an existing CKEditor 5 package with `ckeditor.js`, `package.json` and `webpack.config.js` files.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--dependencies-2">

#### Dependencies

This example uses the following dependencies:

* `@ckeditor/ckeditor5-editor-classic`
* `@ckeditor/ckeditor5-basic-styles`
* `@ckeditor/ckeditor5-essentials`
* `@ckeditor/ckeditor5-paragraph`
* `@ckeditor/ckeditor5-real-time-collaboration`
* `@ckeditor/ckeditor5-dev-utils`
* `@ckeditor/ckeditor5-theme-lark`
* `webpack`
* `webpack-cli`
* `postcss-loader`
* `raw-loader`
* `style-loader`

The `package.json` file dependencies sections should look similar to one below.

```
{
  "dependencies": {
    "@ckeditor/ckeditor5-basic-styles": "41.4.2",
    "@ckeditor/ckeditor5-editor-classic": "41.4.2",
    "@ckeditor/ckeditor5-essentials": "41.4.2",
    "@ckeditor/ckeditor5-paragraph": "41.4.2",
    "@ckeditor/ckeditor5-real-time-collaboration": "41.4.2"
  },
  "devDependencies": {
    "@ckeditor/ckeditor5-dev-utils": "^32.1.2",
    "@ckeditor/ckeditor5-theme-lark": "41.4.2",
    "postcss-loader": "^4.3.0",
    "raw-loader": "^4.0.2",
    "style-loader": "^2.0.0",
    "webpack": "^5.91.0",
    "webpack-cli": "^4.10.0"
  }
}

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--editor-build-configuration">

#### Editor build configuration

This file presents an example of an editor build configuration. It is used by the bundler as an entry file. This `ckeditorcs.js` file should be created based on your `ckeditor.js` file.

```
// ckeditorcs.js

// The editor base creator to use.
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

// All plugins that you would like to use in your editor.
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import RealTimeCollaborativeEditing from '@ckeditor/ckeditor5-real-time-collaboration/src/realtimecollaborativeediting';

class CKEditorCS extends ClassicEditor {}

// Load all plugins you would like to use in your editor this way.
// This is the only way to load plugins into the editor which will then be used in CKEditor Cloud Services.
CKEditorCS.builtinPlugins = [
    Essentials,
    Paragraph,
    Bold,
    Italic,
    RealTimeCollaborativeEditing
];

// Export your editor.
export default CKEditorCS;

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--bundler-configuration-2">

#### Bundler configuration

This file presents an example of the bundler configuration. Here [webpack](https://webpack.js.org/) is used as the bundler.

```
// webpack.config.js

const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

module.exports = {
    entry: './ckeditorcs.js', // Your editor build configuration.
    output: {
        filename: 'editor.bundle.js', // Content of this file is required to upload to CKEditor Cloud Services.
        library: 'CKEditorCS', // It is required to expose you editor class under the "CKEditorCS" name!

        libraryTarget: 'umd',
        libraryExport: 'default'
    },
    module: {
        parser: {
            javascript: {
                dynamicImportMode: 'eager'
            }
        },
        rules: [
            {
                test: /\.svg$/,
                use: [ 'raw-loader' ]
            },
            {
                test: /\.css$/,
                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag'
                        }
                    },
                    {
                        loader: 'postcss-loader',
                        options: styles.getPostCssConfig( {
                            themeImporter: {
                                themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                            },
                            minify: true
                        } )
                    }
                ]
            }
        ]
    },
    performance: { hints: false }
};

```

The most important part here is `output.library` field. Without this, the bundle will not work with the CKEditor Cloud Services server.

```
module.exports = {
    // ...
    output: {
        library: 'CKEditorCS', // It is required to expose you editor class under the "CKEditorCS" name!
        // ...
    },
    // ...
};

```

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--generating-the-bundle-2">

#### Generating the bundle

Run the following commands inside the CKEditor 5 package folder:

```
npm install
npx webpack --mode production

```

This command will result in the generation of the `./dist/editor.bundle.js` file. This is the bundle file which then should be [uploaded to the CKEditor Cloud Services server](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle).

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--editor-bundle-with-watchdog-context-or-super-builds">

#### Editor bundle with watchdog, context or “super builds”

Cloud Services expects the `Editor` class as the default export in the bundled file. If you are using an editor bundle with [Watchdog](#ckeditor5/latest/features/watchdog.html) and [context](#ckeditor5/latest/features/collaboration/context-and-collaboration-features.html) or you are building multiple editors as [“super build”](https://ckeditor.com/docs/ckeditor5/latest/getting-started/legacy/advanced/using-two-editors.html#creating-super-builds), you need to take extra steps to be able to upload these editors.

You can build multiple editor bundles from multiple source files for different purposes. A single webpack build can be then used to bundle all of them. Thanks to this approach, you will have an editor bundle that is compatible with the Cloud Services and you can still use the other editor bundle and take advantage of the “super builds”, watchdog, or context.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--creating-a-legacy-editor-bundle-with-watchdog">

##### Creating a legacy editor bundle with Watchdog

Assuming that you have a `ckeditor.js` source file that is exporting the editor with watchdog:

```
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor.js';
import EditorWatchdog from '@ckeditor/ckeditor5-watchdog/src/editorwatchdog';
// Other plugins imports.

class Editor extends ClassicEditor {}

Editor.builtinPlugins = [
    // Imported plugins.
];

const watchdog = new EditorWatchdog( Editor );
export default watchdog;

```

You can now create the `ckeditorcs.js` source file with the same content as the above file. The only difference is the `export` in this file. Instead of exporting the watchdog, you should export the `Editor` instance: `export default Editor;`.

With the two source files, you can tweak the webpack config to bundle both editors in a single build step:

```
'use strict';

const path = require( 'path' );
const webpack = require( 'webpack' );
const { bundler, styles } = require( '@ckeditor/ckeditor5-dev-utils' );
const { CKEditorTranslationsPlugin } = require( '@ckeditor/ckeditor5-dev-translations' );
const TerserWebpackPlugin = require( 'terser-webpack-plugin' );

const config = {
    devtool: 'source-map',
    performance: { hints: false },
    optimization: {
        minimizer: [
            new TerserWebpackPlugin( {
                sourceMap: true,
                terserOptions: {
                    output: {
                        comments: /^!/
                    }
                },
                extractComments: false
            } )
        ]
    },
    plugins: [
        new CKEditorTranslationsPlugin( {
            language: 'en',
            additionalLanguages: 'all'
        } ),
        new webpack.BannerPlugin( {
            banner: bundler.getLicenseBanner(),
            raw: true
        } )
    ],
    module: {
        parser: {
            javascript: {
                dynamicImportMode: 'eager'
            }
        },
        rules: [
            {
                test: /\.svg$/,
                use: [ 'raw-loader' ]
            },
            {
                test: /\.css$/,
                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag',
                            attributes: {
                                'data-cke': true
                            }
                        }
                    },
                    {
                        loader: 'css-loader'
                    },
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: styles.getPostCssConfig( {
                                themeImporter: {
                                    themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                                },
                                minify: true
                            } )
                        }
                    }
                ]
            }
        ]
    }
};

module.exports = [
    // The first bundle will have the editor with watchdog and can be used in your application.
    {
        ...config,
        entry: path.resolve( __dirname, 'src', 'ckeditor.js' ),
        output: {
            library: 'Watchdog',
            path: path.resolve( __dirname, 'build' ),
            filename: 'ckeditor.js',
            libraryTarget: 'umd',
            libraryExport: 'default'
        }
    },
    // The second bundle will be ready to be uploaded to the Cloud Services server.
    {
        ...config,
        entry: path.resolve( __dirname, 'src', 'ckeditorcs.js' ),
        output: {
            library: 'CKEditorCS',
            path: path.resolve( __dirname, 'build' ),
            filename: 'ckeditorcs.js',
            libraryTarget: 'umd',
            libraryExport: 'default'
        }
    }
];

```

Similarly, you can build multiple bundles if you are using context or “super builds”. In the case of a bundle with context make sure that the bundle for Cloud Services includes all the plugins that the context editor has. For super builds, you can simply create a copy of a source file and export a single editor instance that you would like to upload to Cloud Services.

<a id="cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html--building-the-editor-bundle-with-typescript-2">

#### Building the editor bundle with TypeScript

The examples presented above are using JavaScript in the editor source files. Building the editor bundle with TypeScript is also possible. To start using TypeScript, follow these steps:

1. Integrate TypeScript with webpack. Refer to [this guide](https://webpack.js.org/guides/typescript/) for more details.
2. Change the extension of the editor source file to `.ts`. Adjust the entry path in `webpack.config.js`.
3. Refer to the [Working with TypeScript](https://ckeditor.com/docs/ckeditor5/latest/getting-started/legacy/working-with-typescript.html) guide and adjust the imports and configuration settings if needed.

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html">source file: "cs/latest/examples/editor-bundle/editor-bundle-nodejs.html"</a>

## Creating an editor bundle in Node.js

This article presents examples of a CKEditor 5 [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) in Node.js. An editor bundle is required by CKEditor Cloud Services to enable the [document storage](#cs/latest/guides/collaboration/document-storage.html), [import and export](#cs/latest/guides/collaboration/import-and-export.html) as well as [connection optimization](#cs/latest/guides/collaboration/connection-optimization.html) features.

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--example-bundle">

### Example bundle

The following example presents a minimalistic editor bundle setup. It is based on 3 files - `package.json`, `ckeditorcs.js` and `webpack.config.js`, and is ready to use.

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--dependencies">

#### Dependencies

This example uses the following dependencies:

* `ckeditor5`
* `ckeditor5-premium-features`
* `webpack`
* `webpack-cli`
* `mini-css-extract-plugin`

With the above, the `package.json` file should look like the one below.

```
{
    "name": "ckeditorcs-bundle",
    "version": "1.0.0",
    "private": true,
    "dependencies": {
        "ckeditor5": "^42.0.0",
        "ckeditor5-premium-features": "^42.0.0"
    },
    "devDependencies": {
        "webpack": "^5.91.0",
        "webpack-cli": "^4.10.0",
        "mini-css-extract-plugin": "^2.9.0"
    }
}

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--editor-build-configuration">

#### Editor build configuration

The `ckeditorcs.js` file presents an example of an editor build configuration. It is used by the bundler as an entry file.

```
import {
    // The editor base creator to use.
    ClassicEditor,
    // All plugins that you would like to use in your editor.
    Essentials,
    Paragraph,
    Bold,
    Italic
} from 'ckeditor5';

import {
    // All premium plugins that you would like to use in your editor.
    RealTimeCollaborativeEditing
} from 'ckeditor5-premium-features';

class CKEditorCS extends ClassicEditor {}

// Load all plugins you would like to use in your editor this way.
// This is the only way to load plugins into the editor which will then be used in CKEditor Cloud Services.
CKEditorCS.builtinPlugins = [
    Essentials,
    Paragraph,
    Bold,
    Italic,
    RealTimeCollaborativeEditing
];

// Export your editor.
export default CKEditorCS;

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--bundler-configuration">

#### Bundler configuration

The `webpack.config.js` file presents the bundler configuration. Here [webpack](https://webpack.js.org/) is used as the bundler.

```
const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' );

module.exports = {
    entry: './ckeditorcs.js', // Your editor build configuration.
    output: {
        filename: 'editor.bundle.js', // Content of this file is required to upload to CKEditor Cloud Services.
        library: 'CKEditorCS', // It is required to expose you editor class under the "CKEditorCS" name!

        libraryTarget: 'umd',
        libraryExport: 'default',
        clean: true
    },
    plugins: [
        new MiniCssExtractPlugin()
    ],
    module: {
        parser: {
            javascript: {
                dynamicImportMode: 'eager'
            }
        },
        rules: [
            {
                test: /\.css$/i,
                use: [MiniCssExtractPlugin.loader, 'css-loader']
            }
        ]
    },
    performance: { hints: false }
};

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--generating-the-bundle">

#### Generating the bundle

Run the following commands inside the folder with these files:

```
npm install
npx webpack --mode production

```

This command will result in the generation of the `./dist/editor.bundle.js` file. This is the bundle file which then should be [uploaded to CKEditor Cloud Services server](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle).

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--example-bundle-legacy-configuration">

### Example bundle (legacy configuration)

The following example presents a minimalistic editor bundle setup. It is based on 3 files - `package.json`, `ckeditorcs.js` and `webpack.config.js`, and is ready to use.

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--dependencies-2">

#### Dependencies

This example uses the following dependencies:

* `@ckeditor/ckeditor5-editor-classic`
* `@ckeditor/ckeditor5-basic-styles`
* `@ckeditor/ckeditor5-essentials`
* `@ckeditor/ckeditor5-paragraph`
* `@ckeditor/ckeditor5-real-time-collaboration`
* `@ckeditor/ckeditor5-dev-utils`
* `@ckeditor/ckeditor5-theme-lark`
* `css-loader`
* `postcss-loader`
* `raw-loader`
* `style-loader`
* `webpack`
* `webpack-cli`

With the above, the `package.json` file should look like the one below:

```
{
    "name": "ckeditorcs-bundle",
    "version": "1.0.0",
    "private": true,
    "dependencies": {
        "@ckeditor/ckeditor5-editor-classic": "41.4.2",
        "@ckeditor/ckeditor5-basic-styles": "41.4.2",
        "@ckeditor/ckeditor5-essentials": "41.4.2",
        "@ckeditor/ckeditor5-paragraph": "41.4.2",
        "@ckeditor/ckeditor5-real-time-collaboration": "41.4.2"
    },
    "devDependencies": {
        "@ckeditor/ckeditor5-dev-utils": "^40.2.2",
        "@ckeditor/ckeditor5-theme-lark": "41.4.2",
        "css-loader": "^5.2.7",
        "postcss-loader": "^4.3.0",
        "raw-loader": "^4.0.2",
        "style-loader": "^2.0.0",
        "webpack": "^5.91.0",
        "webpack-cli": "^4.10.0"
    }
}

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--editor-build-configuration-2">

#### Editor build configuration

The `ckeditorcs.js` file presents an example of an editor build configuration. It is used by the bundler as an entry file.

```
// The editor base creator to use.
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

// All plugins that you would like to use in your editor.
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import RealTimeCollaborativeEditing from '@ckeditor/ckeditor5-real-time-collaboration/src/realtimecollaborativeediting';

class CKEditorCS extends ClassicEditor {}

// Load all plugins you would like to use in your editor this way.
// This is the only way to load plugins into the editor which will then be used in CKEditor Cloud Services.
CKEditorCS.builtinPlugins = [
    Essentials,
    Paragraph,
    Bold,
    Italic,
    RealTimeCollaborativeEditing
];

// Export your editor.
export default CKEditorCS;

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--bundler-configuration-2">

#### Bundler configuration

The `webpack.config.js` file presents an example of the bundler configuration. Here [webpack](https://webpack.js.org/) is used as the bundler.

```
const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

module.exports = {
    entry: './ckeditorcs.js', // Your editor build configuration.
    output: {
        filename: 'editor.bundle.js', // Content of this file is required to upload to CKEditor Cloud Services.
        library: 'CKEditorCS', // It is required to expose you editor class under the "CKEditorCS" name!

        libraryTarget: 'umd',
        libraryExport: 'default'
    },
    module: {
        parser: {
            javascript: {
                dynamicImportMode: 'eager'
            }
        },
        rules: [
            {
                test: /\.svg$/,
                use: [ 'raw-loader' ]
            },
            {
                test: /\.css$/,
                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag'
                        }
                    },
                    {
                        loader: 'css-loader'
                    },
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: styles.getPostCssConfig( {
                                themeImporter: {
                                    themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                                },
                                minify: true
                            } )
                        }
                    }
                ]
            }
        ]
    },
    performance: { hints: false }
};

```

<a id="cs/latest/examples/editor-bundle/editor-bundle-nodejs.html--generating-the-bundle-2">

#### Generating the bundle

Run the following commands inside the CKEditor 5 package folder:

```
npm install
npx webpack --mode production

```

This command will result in the generation of the `./dist/editor.bundle.js` file. This is the bundle file which then should be [uploaded to CKEditor Cloud Services server](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle).

<a id="cs/latest/examples/index.html">source file: "cs/latest/examples/index.html"</a>

## Cloud Services examples

This section provides examples on how to implement the following:

* **Token endpoints** – Learn how to create a token endpoint in {% raw %}ASP.NET{% endraw %}, Node.js and PHP.
* **Webhooks** – Learn how to create a webhooks server.
* **Security** – Learn how to create a request signature.
* **On-Premises** – Learn how to create scripts to manage on-premises.
* **Editor bundle** – Learn how to create an editor bundle for the document storage as well as import and export features.
* **Collaboration** – Learn how to create an application that uses the document import and export feature.
* **Server-side Editor API** – Learn how to execute JavaScript code on the server to manipulate document content and collaborative data.

<a id="cs/latest/examples/on-premises/creating-environment-nodejs.html">source file: "cs/latest/examples/on-premises/creating-environment-nodejs.html"</a>

## Creating an environment in Node.js

This article presents an example of using the `Cloud Services Management REST API` to create an environment in Node.js.

<a id="cs/latest/examples/on-premises/creating-environment-nodejs.html--dependencies">

### Dependencies

This example uses `request-promise-native` and core dependencies from Node.js: `crypto`, `url`.

<a id="cs/latest/examples/on-premises/creating-environment-nodejs.html--example">

### Example

The following simple example presents how to create an environment using the `Cloud Services Management REST API`.  
The `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` and `APPLICATION_ENDPOINT` variables should be set to proper values from the configuration.

```
const url = require( 'url' );
const crypto = require( 'crypto' );
const requestPromise = require( 'request-promise-native' );

const ENVIRONMENTS_MANAGEMENT_SECRET_KEY = 'secret';
const APPLICATION_ENDPOINT = 'http://localhost:8000';

( async () => {
    try {
        const newEnvironment = {
            id: _randomString( 20 ), // required length 20
            name: 'Production',
            organizationId: _randomString( 60 ), // required length 10-60
            accessKeys: [
                {
                    value: _randomString( 100 ) // required length 10-120
                }
            ],
            services: [
                {
                    id: _randomString( 24 ), // required length 24
                    type: 'easy-image'
                },
                {
                    id: _randomString( 24 ), // required length 24
                    type: 'collaboration'
                }
            ] // all these services types recommended
        };

        const timestamp = Date.now();

        const uri = `${ APPLICATION_ENDPOINT }/environments`;
        const method = 'POST';

        const signature = _generateSignature(
            ENVIRONMENTS_MANAGEMENT_SECRET_KEY,
            method,
            uri,
            timestamp,
            newEnvironment
        );

        const options = {
            uri,
            method,
            headers: {
                'X-CS-Signature': signature,
                'X-CS-Timestamp': timestamp
            },
            body: newEnvironment,
            json: true,
            rejectUnauthorized: false // required for domains with self signed certificate
        };

        await requestPromise( options );

        console.log( 'New Environment created.' );
        console.log( `EnvironmentId: ${ newEnvironment.id } AccessKey: ${ newEnvironment.accessKeys[ 0 ].value }` );
    } catch ( error ) {
        console.log( 'error:', error.message );
    }
} )();

function _generateSignature( apiSecret, method, uri, timestamp, body ) {
    const path = url.parse( uri ).path;

    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    }

    return hmac.digest( 'hex' );
}

function _randomString( length ) {
    return crypto.randomBytes( length / 2 ).toString( 'hex' );
}

```

<a id="cs/latest/examples/on-premises/creating-environment-nodejs.html--usage">

### Usage

Run:

```
node index.js

```

<a id="cs/latest/examples/security/request-signature-dotnet.html">source file: "cs/latest/examples/security/request-signature-dotnet.html"</a>

## Request signature in ASP.NET

This article presents a sample implementation of a [request signature](#cs/latest/developer-resources/security/request-signature.html) in ASP.NET.

<a id="cs/latest/examples/security/request-signature-dotnet.html--dependencies">

### Dependencies

This example uses `System` dependencies from ASP.NET.

<a id="cs/latest/examples/security/request-signature-dotnet.html--example">

### Example

The following simple example implements the algorithm described in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide. The most important thing is to use the `HMACSHA256` from `System.Security.Cryptography` and pass the parameters in the correct order: `method`, `url`, `timestamp`, `body`.

The `method` parameter should be uppercase and `path` should contain only the relative path and query parameters from the URL, not the full URL address. The full URL address should be converted to e.g. `/webhook?a=1`.

If the algorithm works correctly, it should generate the same signature as the one given below: `56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762` for the following parameters:

* `apiSecret=SECRET`
* `method=POST`
* `uri=http://demo.example.com/webhook?a=1`
* `timestamp=1563276169752`
* `body={a:1}`

```
using System;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Security.Cryptography;

public class Program
{
    public static void Main()
    {
        string signature = GenerateSignature(
            "SECRET",
            "POST",
            "http://demo.example.com/webhook?a=1",
            1563276169752,
            new { a = 1 }
        );

        Console.WriteLine(
            signature == "56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762"
        );
    }

    public static string GenerateSignature(
        string apiSecret,
        string method,
        string uri,
        long timestampMilliseconds,
        object body = null
    )
    {
        string upperMethod = method.ToUpper();
        Uri url = new Uri(uri);
        string path = url.AbsolutePath + url.Query;
        string message = upperMethod + path + timestampMilliseconds;

        if (body != null && (upperMethod == "POST" || upperMethod == "PUT"))
        {
            string bodyString = JsonSerializer.Serialize(body);
            message += bodyString;
        }

        return HmacSha256Digest(message, apiSecret);
    }

    public static string HmacSha256Digest(string message, string secret)
    {
        UTF8Encoding utf8Encoder = new UTF8Encoding();
        byte[] encodedSecret = utf8Encoder.GetBytes(secret);
        byte[] encodedMessage = utf8Encoder.GetBytes(message);

        HMACSHA256 hmac256 = new HMACSHA256(encodedSecret);
        byte[] messageHash = hmac256.ComputeHash(encodedMessage);

        return BitConverter.ToString(messageHash).Replace("-", "").ToLower();
    }
}

```

<a id="cs/latest/examples/security/request-signature-java.html">source file: "cs/latest/examples/security/request-signature-java.html"</a>

## Request signature in Java

This article presents a sample implementation of a [request signature](#cs/latest/developer-resources/security/request-signature.html) in Java.

<a id="cs/latest/examples/security/request-signature-java.html--dependencies">

### Dependencies

This example uses the [util](https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/package-summary.html), [net](https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/net/package-summary.html) and [crypto](https://docs.oracle.com/en/java/javase/18/docs/api/java.base/javax/crypto/package-summary.html) dependencies from the Java SDK.

<a id="cs/latest/examples/security/request-signature-java.html--example">

### Example

The following simple example implements the algorithm described in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide. The most important thing is to calculate `HMAC-SHA-256` using any library using the given parameters in the correct order: `method`, `url`, `timestamp`, `body`.

The `method` parameter should be uppercase and `path` should contain only the relative path and query parameters from the URL, not the full URL address. The full URL address should be converted to e.g. `/webhook?a=1`.

If the algorithm works correctly, it should generate the same signature as the one given below: `56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762` for the following parameters:

* `apiSecret=SECRET`
* `method=POST`
* `uri=http://demo.example.com/webhook?a=1`
* `timestamp=1563276169752`
* `body={a:1}`

```
import java.util.Formatter;
import java.util.Map;
import java.net.URI;
import javax.crypto.spec.SecretKeySpec;
import javax.crypto.Mac;


public class Main {

    private static final String HMAC_SHA256 = "HmacSHA256";

    public static void main(String args[]) throws Exception {
        String expectedSignature = "56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762";
        String signature = generateSignature(
            "SECRET",
            "POST",
            "http://demo.example.com/webhook?a=1",
            1563276169752l,
            "{\"a\":1}"
        );

        System.out.println(signature.equals(expectedSignature));
    }

    private static String toHexString(byte[] bytes) {
        Formatter formatter = new Formatter();

        for (byte b: bytes) {
            formatter.format("%02x", b);
        }

        return formatter.toString();
    }

    public static String calculateHMACSHA256(String data, String key) throws Exception {
        SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(), HMAC_SHA256);
        Mac mac = Mac.getInstance(HMAC_SHA256);

        mac.init(secretKeySpec);

        return toHexString(mac.doFinal(data.getBytes()));
    }

    private static String generateSignature(String secret, String method, String uri, long timestamp) throws Exception {
        return generateSignature(secret, method, uri, timestamp, "");
    }

    private static String generateSignature(String secret, String method, String uri, long timestamp, String bodyString) throws Exception {
        String methodUpperCase = method.toUpperCase();
        URI url = new URI(uri);
        String path = url.getPath();
        String query = url.getQuery();

        if (!query.isBlank()) {
            path = path + "?" + query;
        }

        String signatureData = methodUpperCase + path + timestamp;

        if (bodyString != null) {
            signatureData += bodyString;
        }

        return calculateHMACSHA256(signatureData, secret);
    }
}

```

<a id="cs/latest/examples/security/request-signature-nodejs.html">source file: "cs/latest/examples/security/request-signature-nodejs.html"</a>

## Request signature in Node.js

This article presents a sample implementation of a [request signature](#cs/latest/developer-resources/security/request-signature.html) in Node.js.

<a id="cs/latest/examples/security/request-signature-nodejs.html--dependencies">

### Dependencies

This example uses only core dependecies from Node.js: `crypto` and `url`.

<a id="cs/latest/examples/security/request-signature-nodejs.html--example">

### Example

The following simple example implements the algorithm described in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide. The most important thing is to use the `crypto` module with the appropriate `SHA256` algorithm and give the parameters in the right order: `method`, `url`, `timestamp`, `body`.

The `method` parameter should be provided in uppercase and the `url` should contain only the path from the URL, not the full URL address. The full URL address should be converted to `/webhook?a=1`.

If the algorithm works correctly, it should generate the same signature as the one given below: `56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762` for the following parameters:

* `apiSecret=SECRET`
* `method=POST`
* `uri=http://demo.example.com/webhook?a=1`
* `timestamp=1563276169752`
* `body={a:1}`

```
const crypto = require( 'crypto' );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;

    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    }

    return hmac.digest( 'hex' );
}

const expectedSignature = '56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762';
const generatedSignature = generateSignature(
    'SECRET',
    'POST',
    'http://demo.example.com/webhook?a=1',
    1563276169752,
    { a: 1 }
);

console.log( expectedSignature === generatedSignature );

```

<a id="cs/latest/examples/security/request-signature-nodejs.html--usage">

### Usage

Run:

```
node index.js

```

<a id="cs/latest/examples/security/request-signature-php.html">source file: "cs/latest/examples/security/request-signature-php.html"</a>

## Request signature in PHP

This article presents a sample implementation of a [request signature](#cs/latest/developer-resources/security/request-signature.html) in PHP.

<a id="cs/latest/examples/security/request-signature-php.html--dependencies">

### Dependencies

No external dependencies are required to generate the signature.

<a id="cs/latest/examples/security/request-signature-php.html--example">

### Example

The following simple example implements the algorithm described in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide. The most important thing is to use the `hash_hmac` function with the appropriate `sha256` algorithm and give the parameters in the right order: `method`, `url`, `timestamp`, `body`.

The `method` parameter should be provided in uppercase and the `uri` should contain only the path from the URL, not the full URL address. The full URL address should be converted to `/webhook?a=1`.

If the algorithm works correctly, it should generate the same signature as the one given below: `56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762` for the following parameters:

* `apiSecret=SECRET`
* `method=POST`
* `uri=http://demo.example.com/webhook?a=1`
* `timestamp=1563276169752`
* `body=['a' => 1]`

```
<?php

$secret = 'SECRET';

function generateSignature($apiSecret, $method, $url, $timestamp, $body)
{
    $parsedUrl = parse_url($url);
    $uri = $parsedUrl['path'] ?? '';

    if (isset($parsedUrl['query'])) {
        $uri .= '?' . $parsedUrl['query'];
    }

    $data = $method . $uri . $timestamp;

    if ($body) {
        $data .= json_encode($body);
    }

    $hmac = hash_hmac('sha256', $data, $apiSecret);

    return $hmac;
}

$expectedSignature = '56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762';
$generatedSignature = generateSignature(
    'SECRET',
    'POST',
    'http://demo.example.com/webhook?a=1',
    '1563276169752',
    ['a' => 1]
);

echo $expectedSignature === $generatedSignature ? 'true' : 'false';

```

<a id="cs/latest/examples/security/request-signature-php.html--usage">

### Usage

Run:

```
php index.php

```

The above code should print `true` in the console.

<a id="cs/latest/examples/security/request-signature-python.html">source file: "cs/latest/examples/security/request-signature-python.html"</a>

## Request signature in Python 3

This article presents a sample implementation of a [request signature](#cs/latest/developer-resources/security/request-signature.html) in Python 3.

<a id="cs/latest/examples/security/request-signature-python.html--dependencies">

### Dependencies

This example uses the [hmac](https://docs.python.org/3/library/hmac.html), [hashlib](https://docs.python.org/3/library/hashlib.html), [json](https://docs.python.org/3/library/json.html) and [urllib.parse](https://docs.python.org/3/library/urllib.parse.html) core dependencies from Python 3.

<a id="cs/latest/examples/security/request-signature-python.html--example">

### Example

The following simple example implements the algorithm described in the [Request signature](#cs/latest/developer-resources/security/request-signature.html) guide. The most important thing is to use the `hmac` module with the appropriate `SHA256` algorithm and provide the parameters in the correct order: `method`, `url`, `timestamp`, `body`.

The `method` parameter should be uppercase and `path` should contain only the relative path and query parameters from the URL, not the full URL address. The full URL address should be converted to e.g. `/webhook?a=1`.

If the algorithm works correctly, it should generate the same signature as the one given below: `56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762` for the following parameters:

* `apiSecret=SECRET`
* `method=POST`
* `uri=http://demo.example.com/webhook?a=1`
* `timestamp=1563276169752`
* `body={a:1}`

```
import hmac
import hashlib
import json
import urllib.parse

def hmacDigest(data, key):
    keyEncoded = key.encode()
    dataEncoded = data.encode()

    h = hmac.new(keyEncoded, dataEncoded, hashlib.sha256)

    return h.hexdigest()


def generateSignature(apiSecret, method, uri, timestamp, body):
    url = urllib.parse.urlparse(uri)
    path = url.path

    if (url.query):
        path = path + "?" + url.query

    methodUpperCase = method.upper()
    data = methodUpperCase + path + str(timestamp)

    if (body):
        data += json.dumps(body, separators=(',',':'), ensure_ascii=False)

    return hmacDigest(data, apiSecret)


expectedSignature = "56ac656c7f932c5b775be28949e90af9a2356eae2826539f10ab6526a0eec762"
generatedSignature = generateSignature(
    "SECRET",
    "POST",
    "http://demo.example.com/webhook?a=1",
     1563276169752,
    {"a": 1}
)

print(generatedSignature == expectedSignature)

```

<a id="cs/latest/examples/security/request-signature-python.html--usage">

### Usage

Run:

```
python3 index.py

```

<a id="cs/latest/examples/server-side-editor-api-examples/extract-document-content-in-nodejs.html">source file: "cs/latest/examples/server-side-editor-api-examples/extract-document-content-in-nodejs.html"</a>

## Extract document content in Node.js

This article presents an example of an application that allows for extracting document content using the [Server-side Editor API](#cs/latest/developer-resources/server-side-editor-api/editor-scripts.html) feature.

<a id="cs/latest/examples/server-side-editor-api-examples/extract-document-content-in-nodejs.html--dependencies">

### Dependencies

This example uses the following dependencies:

* `axios`

It also uses core dependencies from Node.js: `crypto`.

<a id="cs/latest/examples/server-side-editor-api-examples/extract-document-content-in-nodejs.html--example">

### Example

This example demonstrates how to use the Server-side Editor API to extract document content using Node.js. Make sure you have Node.js and npm installed before following these steps.

1. Create a new project and install dependencies:

```
mkdir cs-sse-api-example && cd cs-sse-api-example && npm init -y && npm i axios && touch sse-api.js

```

1. Open `cs-sse-api-example/sse-api.js` and paste the following code snippet:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Set document id
const documentId = 'my_document_id';

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';
const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/collaborations/${ documentId }/evaluate-script`;

// Example script that extracts document content
const script = `
    const data = editor.getData();

    return {
        content: data,
        wordCount: data.split(' ').length,
        characterCount: data.length
    };
`;

const body = {
    'script': script,
    'user': {
        'id': 'txQ9sTfqmXUyWU5LmDbr',
        'name': 'System Process',
    }
};

const CSTimestamp = Date.now();
const config = {
    headers: {
        'X-CS-Timestamp': CSTimestamp,
        'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body )
    },
};

axios.post( apiEndpoint, body, config )
    .then( response => {
        console.log( 'Status:', response.status );
        console.log( 'Response data:', response.data );
    } ).catch( error => {
        console.log( 'Error:', error.message );
        console.log( 'Response data:', error.response.data );
    } );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    };

    return hmac.digest( 'hex' );
}

```

1. Update your credentials and the `documentId` values in the code snippet.
2. Execute the script:

```
node sse-api.js

```

After a successful response with a status code `201`, you should see the document content, word count, and character count in the console output.

<a id="cs/latest/examples/token-endpoints/dotnet.html">source file: "cs/latest/examples/token-endpoints/dotnet.html"</a>

## Token endpoint in ASP.NET

This article presents a simple [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) example for creating JSON Web Tokens (JWT) implemented in ASP.NET. The tokens are used by CKEditor Cloud Services to authenticate users.

<a id="cs/latest/examples/token-endpoints/dotnet.html--dependencies">

### Dependencies

All code examples use the [System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/) library.

If you are using the [package manager console](https://docs.microsoft.com/en-us/nuget/tools/package-manager-console) in Visual Studio, you can run the following:

```
Install-Package System.IdentityModel.Tokens.Jwt

```

<a id="cs/latest/examples/token-endpoints/dotnet.html--examples">

### Examples

When creating a token endpoint to integrate with [Collaboration](#cs/latest/guides/collaboration/quick-start.html), the token payload should contain the environment ID and user data.

<a id="cs/latest/examples/token-endpoints/dotnet.html--real-time-collaboration-features">

#### Real-time collaboration features

```
using System;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using System.Collections.Generic;

namespace CSTokenExample
{
    class Program
    {
        static string createCSToken(string environmentId, string accessKey)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(accessKey));

            var signingCredentials = new SigningCredentials(securityKey, "HS256");
            var header = new JwtHeader(signingCredentials);

            var dateTimeOffset = new DateTimeOffset(DateTime.UtcNow);

            var payload = new JwtPayload
            {
                { "aud", environmentId },
                { "iat", dateTimeOffset.ToUnixTimeSeconds() },
                { "sub", "user-123" },
                { "user", new Dictionary<string, string> {
                    { "email", "joe.doe@example.com" },
                    { "name", "Joe Doe" }
                } },
                { "auth", new Dictionary<string, object> {
                    { "collaboration", new Dictionary<string, object> {
                        { "*", new Dictionary<string, string> {
                            { "role", "writer" }
                        } }
                    } }
                } }
            };

            var securityToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();

            return handler.WriteToken(securityToken);
        }

        static void Main(string[] args)
        {
            string accessKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";
            string environmentId = "LJRQ1bju55p6a47RwadH";

            var tokenString = createCSToken(environmentId, accessKey);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            Console.WriteLine(tokenString);
        }
    }
}

```

`accessKey` and `environmentId` should be replaced with the keys provided by the [Customer Portal](https://portal.ckeditor.com/) for SaaS or by the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application. User data can be taken from the session or the database.

You should then pass the token to the client in an HTTP response of the token endpoint. Do not forget to authenticate the user in your application before you send the token. If the user is unauthenticated, the token endpoint should return an error or redirect to the login page. You should also make sure the token is sent via an encrypted channel.

<a id="cs/latest/examples/token-endpoints/dotnet.html--ckeditor-ai">

#### CKEditor AI

When creating a token endpoint for [CKEditor AI](#cs/latest/guides/ckeditor-ai/overview.html), the token payload should include AI-specific permissions in the `auth.ai.permissions` array. For a full list of available permissions, see the [Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

```
using System;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using System.Collections.Generic;

namespace CSTokenExample
{
    class Program
    {
        static string createCSToken(string environmentId, string accessKey)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(accessKey));

            var signingCredentials = new SigningCredentials(securityKey, "HS256");
            var header = new JwtHeader(signingCredentials);

            var dateTimeOffset = new DateTimeOffset(DateTime.UtcNow);

            var payload = new JwtPayload
            {
                { "aud", environmentId },
                { "iat", dateTimeOffset.ToUnixTimeSeconds() },
                { "sub", "user-123" },
                { "user", new Dictionary<string, string> {
                    { "email", "joe.doe@example.com" },
                    { "name", "Joe Doe" }
                } },
                { "auth", new Dictionary<string, object> {
                    { "ai", new Dictionary<string, object> {
                        { "permissions", new List<string> {
                            "ai:conversations:*",
                            "ai:models:agent",
                            "ai:actions:system:*",
                            "ai:reviews:system:*"
                        } }
                    } }
                } }
            };

            var securityToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();

            return handler.WriteToken(securityToken);
        }

        static void Main(string[] args)
        {
            string accessKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";
            string environmentId = "LJRQ1bju55p6a47RwadH";

            var tokenString = createCSToken(environmentId, accessKey);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            Console.WriteLine(tokenString);
        }
    }
}

```

If you use both collaboration and AI, combine both `auth.collaboration` and `auth.ai` in a single token payload.

<a id="cs/latest/examples/token-endpoints/dotnet.html--easy-image-export-to-pdf-and-import-and-export-to-word">

#### Easy Image, Export to PDF and Import and Export to Word

The token endpoint for Easy Image and the Export to Word/PDF features does not require adding user data. You can therefore skip the `user` and `auth` properties in the token payload.

<a id="cs/latest/examples/token-endpoints/dotnet.html--export-to-pdf-and-import-and-export-to-word-on-premises">

#### Export to PDF and Import and Export to Word On-Premises

Tokens for PDF Converter and DOCX Converter On-Premises do not require any additional claims, so you can create the token with an empty payload.

In this implementation, `accessKey` has been replaced by `SECRET_KEY` \- a variable set during the [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/installation.html)/[Export to PDF](#cs/latest/onpremises/pdf-onpremises/installation.html) On-Premises instance installation.

```
using System;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using System.Collections.Generic;

namespace CSTokenExample
{
    class Program
    {
        static string createCSToken(string secretKey)
        {
            var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(secretKey));

            var signingCredentials = new SigningCredentials(securityKey, "HS256");
            var header = new JwtHeader(signingCredentials);

            var dateTimeOffset = new DateTimeOffset(DateTime.UtcNow);

            var payload = new JwtPayload
            {
                { "iat", dateTimeOffset.ToUnixTimeSeconds() }
            };

            var securityToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();

            return handler.WriteToken(securityToken);
        }

        static void Main(string[] args)
        {
            string secretKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";

            var tokenString = createCSToken(secretKey);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            Console.WriteLine(tokenString);
        }
    }
}

```

If you create your own token endpoint, do not forget to authenticate the user before you send the token.

<a id="cs/latest/examples/token-endpoints/dotnet.html--example-response">

### Example response

The result should be in a plain text format.

```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMSlJRMWJqdTU1cDZhNDdSd2FkSCIsImlhdCI6MTY0OTIyOTQyMiwic3ViIjoidXNlci0xMjMiLCJ1c2VyIjp7ImVtYWlsIjoiam9lLmRvZUBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2UgRG9lIn0sImF1dGgiOnsiY29sbGFib3JhdGlvbiI6eyIqIjp7InJvbGUiOiJ3cml0ZXIifX19fQ._V-HXKKHU1E-saZxk4JTvgXdh1I7793nCEK91ubSZHY

```

<a id="cs/latest/examples/token-endpoints/dotnet.html--debugging">

### Debugging

For debugging purposes [jwt.io](https://jwt.io) can be used.

<a id="cs/latest/examples/token-endpoints/java.html">source file: "cs/latest/examples/token-endpoints/java.html"</a>

## Token endpoint in Java

This article presents a simple [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) example for creating JSON Web Tokens (JWT) implemented in Java. The tokens are used by CKEditor Cloud Services to authenticate users.

<a id="cs/latest/examples/token-endpoints/java.html--dependencies">

### Dependencies

All examples use the [jjwt](https://github.com/jwtk/jjwt) library for creating tokens.

For installation instructions check the [official guide](https://github.com/jwtk/jjwt#install).

<a id="cs/latest/examples/token-endpoints/java.html--examples">

### Examples

When creating a token endpoint to integrate with [Collaboration](#cs/latest/guides/collaboration/quick-start.html), the token payload should contain the environment ID and user data.

<a id="cs/latest/examples/token-endpoints/java.html--real-time-collaboration-features">

#### Real-time collaboration features

```
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

import java.io.UnsupportedEncodingException;
import java.util.HashMap;
import java.util.Map;
import java.security.Key;

public class Main {

    private static String createCSToken(String accessKey, String environmentId) throws UnsupportedEncodingException {
        Key key = Keys.hmacShaKeyFor(accessKey.getBytes("ASCII"));

        Map<String, Object> payload = new HashMap<>() {{
            put("aud", environmentId);
            put("iat", System.currentTimeMillis() / 1000);
            put("sub", "user-123");
            put("user", new HashMap<>() {{
                put("email", "joe.doe@example.com");
                put("name", "Joe Doe");
            }});
            put("auth", new HashMap<>() {{
                put("collaboration", new HashMap<>() {{
                    put("*", new HashMap<>() {{
                        put("role", "writer");
                    }});
                }});
            }});
        }};

        return Jwts.builder().addClaims(payload).signWith(key).compact();
    }

    public static void main(String[] args) {
        String accessKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";
        String environmentId = "LJRQ1bju55p6a47RwadH";

        try {
            var tokenString = createCSToken(accessKey, environmentId);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            System.out.println(tokenString);
        } catch (Exception exception) {
            System.out.println(exception);
        }
    }
}

```

`accessKey` and `environmentId` should be replaced with the keys provided by the [Customer Portal](https://portal.ckeditor.com/) for SaaS or by the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application. User data can be taken from the session or the database.

You should then pass the token to the client in an HTTP response of the token endpoint. Do not forget to authenticate the user in your application before you send the token. If the user is unauthenticated, the token endpoint should return an error or redirect to the login page. You should also make sure the token is sent via an encrypted channel.

<a id="cs/latest/examples/token-endpoints/java.html--ckeditor-ai">

#### CKEditor AI

When creating a token endpoint for [CKEditor AI](#cs/latest/guides/ckeditor-ai/overview.html), the token payload should include AI-specific permissions in the `auth.ai.permissions` array. For a full list of available permissions, see the [Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

```
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

import java.io.UnsupportedEncodingException;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.security.Key;

public class Main {

    private static String createCSToken(String accessKey, String environmentId) throws UnsupportedEncodingException {
        Key key = Keys.hmacShaKeyFor(accessKey.getBytes("ASCII"));

        Map<String, Object> payload = new HashMap<>() {{
            put("aud", environmentId);
            put("iat", System.currentTimeMillis() / 1000);
            put("sub", "user-123");
            put("user", new HashMap<>() {{
                put("email", "joe.doe@example.com");
                put("name", "Joe Doe");
            }});
            put("auth", new HashMap<>() {{
                put("ai", new HashMap<>() {{
                    put("permissions", Arrays.asList(
                        "ai:conversations:*",
                        "ai:models:agent",
                        "ai:actions:system:*",
                        "ai:reviews:system:*"
                    ));
                }});
            }});
        }};

        return Jwts.builder().addClaims(payload).signWith(key).compact();
    }

    public static void main(String[] args) {
        String accessKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";
        String environmentId = "LJRQ1bju55p6a47RwadH";

        try {
            var tokenString = createCSToken(accessKey, environmentId);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            System.out.println(tokenString);
        } catch (Exception exception) {
            System.out.println(exception);
        }
    }
}

```

If you use both collaboration and AI, combine both `auth.collaboration` and `auth.ai` in a single token payload.

<a id="cs/latest/examples/token-endpoints/java.html--easy-image-export-to-pdf-and-import-and-export-to-word">

#### Easy Image, Export to PDF and Import and Export to Word

The token endpoint for Easy Image and the Export to Word/PDF features does not require adding user data. You can therefore skip the `user` and `auth` properties in the token payload.

<a id="cs/latest/examples/token-endpoints/java.html--export-to-pdf-and-import-and-export-to-word-on-premises">

#### Export to PDF and Import and Export to Word On-Premises

Tokens for PDF Converter and DOCX Converter On-Premises do not require any additional claims, so you can create the token with an empty payload.

In this implementation, `accessKey` has been replaced by `SECRET_KEY` \- a variable set during the [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/installation.html)/[Export to PDF](#cs/latest/onpremises/pdf-onpremises/installation.html) On-Premises instance installation.

```
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

import java.io.UnsupportedEncodingException;
import java.util.Date;
import java.security.Key;

public class Main {
    private static String createCSToken(String secretKey) throws UnsupportedEncodingException {
        Key key = Keys.hmacShaKeyFor(secretKey.getBytes("ASCII"));

        return Jwts.builder().setIssuedAt(new Date()).signWith(key).compact();
    }

    public static void main(String[] args) {
        String secretKey = "w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy";

        try {
            var tokenString = createCSToken(secretKey);

            // Here we are printing the token to the console. In a real usage scenario
            // it should be returned in an HTTP response of the token endpoint.
            System.out.println(tokenString);
        } catch (Exception exception) {
            System.out.println(exception);
        }
    }
}

```

<a id="cs/latest/examples/token-endpoints/java.html--example-response">

### Example response

The result should be in a plain text format.

```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMSlJRMWJqdTU1cDZhNDdSd2FkSCIsImlhdCI6MTY0OTIyOTQyMiwic3ViIjoidXNlci0xMjMiLCJ1c2VyIjp7ImVtYWlsIjoiam9lLmRvZUBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2UgRG9lIn0sImF1dGgiOnsiY29sbGFib3JhdGlvbiI6eyIqIjp7InJvbGUiOiJ3cml0ZXIifX19fQ._V-HXKKHU1E-saZxk4JTvgXdh1I7793nCEK91ubSZHY

```

<a id="cs/latest/examples/token-endpoints/java.html--debugging">

### Debugging

For debugging purposes [jwt.io](https://jwt.io) can be used.

<a id="cs/latest/examples/token-endpoints/nodejs.html">source file: "cs/latest/examples/token-endpoints/nodejs.html"</a>

## Token endpoint in Node.js

This article presents a simple [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) example for creating JSON Web Tokens (JWT) implemented in Node.js. The tokens are used by CKEditor Cloud Services to authenticate users.

<a id="cs/latest/examples/token-endpoints/nodejs.html--dependencies">

### Dependencies

All examples use the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) library for creating tokens and [express](https://www.npmjs.com/package/express) to create the HTTP endpoint.

```
npm install express jsonwebtoken

```

<a id="cs/latest/examples/token-endpoints/nodejs.html--examples">

### Examples

When creating a token endpoint to integrate with [Collaboration](#cs/latest/guides/collaboration/quick-start.html), the token payload should contain the environment ID and user data.

<a id="cs/latest/examples/token-endpoints/nodejs.html--real-time-collaboration-features">

#### Real-time collaboration features

```
const express = require( 'express' );
const jwt = require( 'jsonwebtoken' );

const accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';
const environmentId = 'LJRQ1bju55p6a47RwadH';

const app = express();

app.use( ( req, res, next ) => {
    res.setHeader( 'Access-Control-Allow-Origin', '*' );
    res.setHeader( 'Access-Control-Allow-Methods', 'GET' );

    next();
} );

app.get( '/', ( req, res ) => {
    const payload = {
        aud: environmentId,
        sub: 'user-123',
        user: {
            email: 'joe.doe@example.com',
            name: 'Joe Doe'
        },
        auth: {
            'collaboration': {
                '*': {
                    'role': 'writer'
                }
            }
        }
    };

    const result = jwt.sign( payload, accessKey, { algorithm: 'HS256', expiresIn: '24h' } );

    res.send( result );
} );

app.listen( 8080, () => console.log( 'Listening on port 8080' ) );

```

`accessKey` and `environmentId` should be replaced with the keys provided by the [Customer Portal](https://portal.ckeditor.com/) for SaaS or by the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application. User data can be taken from the session or the database. You do not need to add `iat` because `jwt.sign()` will add it by itself.

You should then pass the token to the client, for example by sending a plain string or by rendering a page that will contain this token. If the user is unauthenticated, the token endpoint should return an error or redirect to the login page. Also, you should make sure that the token is sent via an encrypted channel.

<a id="cs/latest/examples/token-endpoints/nodejs.html--ckeditor-ai">

#### CKEditor AI

When creating a token endpoint for [CKEditor AI](#cs/latest/guides/ckeditor-ai/overview.html), the token payload should include AI-specific permissions in the `auth.ai.permissions` array. For a full list of available permissions, see the [Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

```
const express = require( 'express' );
const jwt = require( 'jsonwebtoken' );

const accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';
const environmentId = 'LJRQ1bju55p6a47RwadH';

const app = express();

app.use( ( req, res, next ) => {
    res.setHeader( 'Access-Control-Allow-Origin', '*' );
    res.setHeader( 'Access-Control-Allow-Methods', 'GET' );

    next();
} );

app.get( '/', ( req, res ) => {
    const payload = {
        aud: environmentId,
        sub: 'user-123',
        user: {
            email: 'joe.doe@example.com',
            name: 'Joe Doe'
        },
        auth: {
            'ai': {
                'permissions': [
                    'ai:conversations:*',
                    'ai:models:agent',
                    'ai:actions:system:*',
                    'ai:reviews:system:*'
                ]
            }
        }
    };

    const result = jwt.sign( payload, accessKey, { algorithm: 'HS256', expiresIn: '24h' } );

    res.send( result );
} );

app.listen( 8080, () => console.log( 'Listening on port 8080' ) );

```

If you use both collaboration and AI, combine both `auth.collaboration` and `auth.ai` in a single token payload.

<a id="cs/latest/examples/token-endpoints/nodejs.html--easy-image-export-to-pdf-and-import-and-export-to-word">

#### Easy Image, Export to PDF and Import and Export to Word

The token endpoint for Easy Image and the Export to Word/PDF features does not require adding user data. You can therefore skip the `user` and `auth` properties in the token payload.

<a id="cs/latest/examples/token-endpoints/nodejs.html--export-to-pdf-and-import-and-export-to-word-on-premises">

#### Export to PDF and Import and Export to Word On-Premises

Tokens for PDF Converter and DOCX Converter On-Premises do not require any additional claims, so you can create the token with an empty payload.

In this implementation, `accessKey` has been replaced by `SECRET_KEY` \- a variable set during the [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/installation.html)/[Export to PDF](#cs/latest/onpremises/pdf-onpremises/installation.html) On-Premises instance installation.

```
const express = require( 'express' );
const jwt = require( 'jsonwebtoken' );

const SECRET_KEY = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';

const app = express();

app.use( ( req, res, next ) => {
    res.setHeader( 'Access-Control-Allow-Origin', '*' );
    res.setHeader( 'Access-Control-Allow-Methods', 'GET' );

    next();
} );

app.get( '/', ( req, res ) => {
    const result = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );

    res.send( result );
} );

app.listen( 8080, () => console.log( 'Listening on port 8080' ) );

```

If you create your own token endpoint, do not forget to authenticate the user before you send the token. You can use [Passport](http://www.passportjs.org) for this.

<a id="cs/latest/examples/token-endpoints/nodejs.html--usage">

### Usage

Start the server by running:

```
node server

```

Now you can get the token with a simple request:

```
http://localhost:8080/

```

<a id="cs/latest/examples/token-endpoints/nodejs.html--example-response">

### Example response

The result should be in a plain text format.

```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMSlJRMWJqdTU1cDZhNDdSd2FkSCIsImlhdCI6MTY0OTIyOTQyMiwic3ViIjoidXNlci0xMjMiLCJ1c2VyIjp7ImVtYWlsIjoiam9lLmRvZUBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2UgRG9lIn0sImF1dGgiOnsiY29sbGFib3JhdGlvbiI6eyIqIjp7InJvbGUiOiJ3cml0ZXIifX19fQ._V-HXKKHU1E-saZxk4JTvgXdh1I7793nCEK91ubSZHY

```

<a id="cs/latest/examples/token-endpoints/nodejs.html--debugging">

### Debugging

For debugging purposes, [jwt.io](https://jwt.io) can be used.

<a id="cs/latest/examples/token-endpoints/php.html">source file: "cs/latest/examples/token-endpoints/php.html"</a>

## Token endpoint in PHP

This article presents a simple [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) example for creating JSON Web Tokens (JWT) implemented in PHP. The tokens are used by CKEditor Cloud Services to authenticate users.

<a id="cs/latest/examples/token-endpoints/php.html--dependencies">

### Dependencies

All examples use the [firebase/php-jwt](https://firebaseopensource.com/projects/firebase/php-jwt/) library for creating tokens.

```
composer require firebase/php-jwt

```

<a id="cs/latest/examples/token-endpoints/php.html--examples">

### Examples

When creating a token endpoint to integrate with [Collaboration](#cs/latest/guides/collaboration/quick-start.html), the token payload should contain the environment ID and user data.

<a id="cs/latest/examples/token-endpoints/php.html--real-time-collaboration-features">

#### Real-time collaboration features

```
<?php
require __DIR__ . '/vendor/autoload.php';

use \Firebase\JWT\JWT;

$accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';
$environmentId = 'LJRQ1bju55p6a47RwadH';

$payload = array(
    'aud' => $environmentId,
    'iat' => time(),
    'sub' => 'user-123',
    'user' => array(
        'email' => 'joe.doe@example.com',
        'name' => 'Joe Doe'
    ),
    'auth' => array(
        'collaboration' => array(
            '*' => array(
                'role' => 'writer',
            )
        )
    )
);

$jwt = JWT::encode($payload, $accessKey, 'HS256');

// Here we are printing the token to the console. In a real usage scenario
// it should be returned in an HTTP response of the token endpoint.
echo $jwt;
?>

```

`$accessKey` and `$environmentId` should be replaced with the keys provided by the [Customer Portal](https://portal.ckeditor.com/) for SaaS or by the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application. User data can be taken from the session or the database.  
You should then pass the token to the client, for example by sending a plain string or by rendering a page that will contain this token. If the user is unauthenticated, the token endpoint should return an error or redirect to the login page. Also, you should make sure that the token is sent via an encrypted channel.

<a id="cs/latest/examples/token-endpoints/php.html--ckeditor-ai">

#### CKEditor AI

When creating a token endpoint for [CKEditor AI](#cs/latest/guides/ckeditor-ai/overview.html), the token payload should include AI-specific permissions in the `auth.ai.permissions` array. For a full list of available permissions, see the [Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

```
<?php
require __DIR__ . '/vendor/autoload.php';

use \Firebase\JWT\JWT;

$accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';
$environmentId = 'LJRQ1bju55p6a47RwadH';

$payload = array(
    'aud' => $environmentId,
    'iat' => time(),
    'sub' => 'user-123',
    'user' => array(
        'email' => 'joe.doe@example.com',
        'name' => 'Joe Doe'
    ),
    'auth' => array(
        'ai' => array(
            'permissions' => array(
                'ai:conversations:*',
                'ai:models:agent',
                'ai:actions:system:*',
                'ai:reviews:system:*'
            )
        )
    )
);

$jwt = JWT::encode($payload, $accessKey, 'HS256');

echo $jwt;
?>

```

If you use both collaboration and AI, combine both `auth.collaboration` and `auth.ai` in a single token payload.

<a id="cs/latest/examples/token-endpoints/php.html--easy-image-export-to-pdf-and-import-and-export-to-word">

#### Easy Image, Export to PDF and Import and Export to Word

The token endpoint for Easy Image and the Export to Word/PDF features does not require adding user data. You can therefore skip the `user` and `auth` properties in the token payload.

<a id="cs/latest/examples/token-endpoints/php.html--export-to-pdf-and-import-and-export-to-word-on-premises">

#### Export to PDF and Import and Export to Word On-Premises

Tokens for PDF Converter and DOCX Converter On-Premises do not require any additional claims, so you can create the token with an empty payload.

In this implementation, `accessKey` has been replaced by `SECRET_KEY` \- a variable set during the [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/installation.html)/[Export to PDF](#cs/latest/onpremises/pdf-onpremises/installation.html) On-Premises instance installation.

```
<?php
require __DIR__ . '/vendor/autoload.php';

use \Firebase\JWT\JWT;

$secretKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy';

$payload = array(
    'iat' => time()
);

$jwt = JWT::encode($payload, $secretKey, 'HS256');

// Here we are printing the token to the console. In a real usage scenario
// it should be returned in an HTTP response of the token endpoint.
echo $jwt;
?>

```

If you create your own token endpoint, do not forget to authenticate the user before you send the token.

<a id="cs/latest/examples/token-endpoints/php.html--example-response">

### Example response

The result should be in a plain text format.

```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMSlJRMWJqdTU1cDZhNDdSd2FkSCIsImlhdCI6MTY0OTIyOTQyMiwic3ViIjoidXNlci0xMjMiLCJ1c2VyIjp7ImVtYWlsIjoiam9lLmRvZUBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2UgRG9lIn0sImF1dGgiOnsiY29sbGFib3JhdGlvbiI6eyIqIjp7InJvbGUiOiJ3cml0ZXIifX19fQ._V-HXKKHU1E-saZxk4JTvgXdh1I7793nCEK91ubSZHY

```

<a id="cs/latest/examples/token-endpoints/php.html--debugging">

### Debugging

For debugging purposes [jwt.io](https://jwt.io) can be used.

<a id="cs/latest/examples/token-endpoints/python.html">source file: "cs/latest/examples/token-endpoints/python.html"</a>

## Token endpoint in Python 3

This article presents a simple [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) example for creating JSON Web Tokens (JWT) implemented in python. The tokens are used by CKEditor Cloud Services to authenticate users.

<a id="cs/latest/examples/token-endpoints/python.html--dependencies">

### Dependencies

All code examples use the [pyjwt](https://pypi.org/project/pyjwt/), [Flask](https://pypi.org/project/Flask/) and [Flask-Cors](https://pypi.org/project/Flask-Cors/) libraries.

If you are using [Python Package Index](https://pypi.org/), you can run the following command in a terminal:

```
python3 -m pip install flask flask_cors pyjwt

```

<a id="cs/latest/examples/token-endpoints/python.html--examples">

### Examples

When creating a token endpoint to integrate with [Collaboration](#cs/latest/guides/collaboration/quick-start.html), the token payload should contain the environment ID and user data.

<a id="cs/latest/examples/token-endpoints/python.html--real-time-collaboration-features">

#### Real-time collaboration features

```
import jwt

from time import time
from flask import Flask
from flask_cors import CORS

accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy'
environmentId = 'LJRQ1bju55p6a47RwadH'

app = Flask(__name__)
CORS(app)


@app.route('/')
def main():
    timestamp = int(time())

    payload = {
        'aud': environmentId,
        'iat': timestamp,
        'sub': 'user-123',
        'user': {
            'email': 'joe.doe@example.com',
            'name': 'Joe Doe'
        },
        'auth': {
            'collaboration': {
                '*': {
                    'role': 'writer'
                }
            }
        }
    }

    return jwt.encode(payload, accessKey)

if __name__ == '__main__':
    app.run(port='8080')

```

`accessKey` and `environmentId` should be replaced with the keys provided by the [Customer Portal](https://portal.ckeditor.com/) for SaaS or by the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application. User data can be taken from the session or the database.

You should then pass the token to the client, for example by sending a plain string or by rendering a page that will contain this token. If the user is unauthenticated, the token endpoint should return an error or redirect to the login page. Also, you should make sure that the token is sent via an encrypted channel.

<a id="cs/latest/examples/token-endpoints/python.html--ckeditor-ai">

#### CKEditor AI

When creating a token endpoint for [CKEditor AI](#cs/latest/guides/ckeditor-ai/overview.html), the token payload should include AI-specific permissions in the `auth.ai.permissions` array. For a full list of available permissions, see the [Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

```
import jwt

from time import time
from flask import Flask
from flask_cors import CORS

accessKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy'
environmentId = 'LJRQ1bju55p6a47RwadH'

app = Flask(__name__)
CORS(app)


@app.route('/')
def main():
    timestamp = int(time())

    payload = {
        'aud': environmentId,
        'iat': timestamp,
        'sub': 'user-123',
        'user': {
            'email': 'joe.doe@example.com',
            'name': 'Joe Doe'
        },
        'auth': {
            'ai': {
                'permissions': [
                    'ai:conversations:*',
                    'ai:models:agent',
                    'ai:actions:system:*',
                    'ai:reviews:system:*'
                ]
            }
        }
    }

    return jwt.encode(payload, accessKey)

if __name__ == '__main__':
    app.run(port='8080')

```

If you use both collaboration and AI, combine both `auth.collaboration` and `auth.ai` in a single token payload.

<a id="cs/latest/examples/token-endpoints/python.html--easy-image-export-to-pdf-and-import-and-export-to-word">

#### Easy Image, Export to PDF and Import and Export to Word

The token endpoint for Easy Image and the Export to Word/PDF features does not require adding user data. You can therefore skip the `user` and `auth` properties in the token payload.

<a id="cs/latest/examples/token-endpoints/python.html--export-to-pdf-and-import-and-export-to-word-on-premises">

#### Export to PDF and Import and Export to Word On-Premises

Tokens for PDF Converter and DOCX Converter On-Premises do not require any additional claims, so you can create the token with an empty payload.

In this implementation, `accessKey` has been replaced by `SECRET_KEY` \- a variable set during the [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/installation.html)/[Export to PDF](#cs/latest/onpremises/pdf-onpremises/installation.html) On-Premises instance installation.

```
import jwt

from time import time
from flask import Flask
from flask_cors import CORS

secretKey = 'w1lnWEN63FPKxBNmxHN7WpfW2IoYVYca5moqIUKfWesL1Ykwv34iR5xwfWLy'

app = Flask(__name__)
CORS(app)


@app.route('/')
def main():
    timestamp = int(time())

    payload = {
        'iat': timestamp
    }

    return jwt.encode( payload, secretKey)

if __name__ == '__main__':
    app.run(port='8080')

```

If you create your own token endpoint, do not forget to authenticate the user before you send the token.

<a id="cs/latest/examples/token-endpoints/python.html--usage">

### Usage

Start the server by running:

```
python index.py

```

Now you can get the token with a simple request:

```
http://localhost:8080/

```

<a id="cs/latest/examples/token-endpoints/python.html--example-response">

### Example response

The response should be in a plain text format.

```
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMSlJRMWJqdTU1cDZhNDdSd2FkSCIsImlhdCI6MTY0ODgwNzY2Miwic3ViIjoidXNlci0xMjMiLCJ1c2VyIjp7ImVtYWlsIjoiam9lLmRvZUBleGFtcGxlLmNvbSIsIm5hbWUiOiJKb2UgRG9lIn0sImF1dGgiOnsiY29sbGFib3JhdGlvbiI6eyIqIjp7InJvbGUiOiJ3cml0ZXIifX19fQ.QZLzRz9SF8JP2zK9vENewmD75Og6z1a83fDt5SXuLF4

```

<a id="cs/latest/examples/token-endpoints/python.html--debugging">

### Debugging

For debugging purposes [jwt.io](https://jwt.io) can be used.

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html">source file: "cs/latest/examples/webhooks/webhooks-server-nodejs.html"</a>

## Webhooks server in Node.js

This article presents a simple [webhooks server](#cs/latest/developer-resources/webhooks/server.html) example.

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html--dependencies">

### Dependencies

Both examples use the Express library to create the HTTP endpoint.  
Also, for local development purposes, a tunneling service is required. This example uses [ngrok](https://ngrok.com/).

```
npm install express jsonwebtoken

```

You can download ngrok here: <https://ngrok.com/download>.

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html--examples">

### Examples

Below are two examples of a webhooks server built on Express.

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html--example-without-checking-the-request-signature">

#### Example without checking the request signature

This is a very simple example, with the server logging the `body` from the request to the console. The `body` contains the complete [webhook information](#cs/latest/developer-resources/webhooks/overview.html--webhook-format) sent from CKEditor Cloud Services.

```
const express = require( 'express' );
const app = express();
app.use( express.json() );

app.post( '/', ( req, res ) => {
    console.log( 'received webhook', req.body );
    res.sendStatus( 200 );
} );

app.listen( 9000, () => console.log( 'Node.js server started on port 9000.' ) );

```

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html--example-with-checking-the-request-signature">

#### Example with checking the request signature

This example is more complex because while the server logs the webhook information to the console, it also checks if the request was sent from the CKEditor Cloud Services servers and was [signed](#cs/latest/developer-resources/security/request-signature.html) with the correct [API secret](#cs/latest/developer-resources/security/api-secret.html).

Several variables are needed to generate and check the signature. The [API secret](#cs/latest/developer-resources/security/api-secret.html) is available in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises, the rest of the parameters are in the request:

* `method`: `req.method`
* `url`: `req.url`
* `timestamp`: `req.headers[ 'x-cs-timestamp' ]`
* `body`: `req.rawBody`

Please note that the `rawBody` field was added by the following configuration:

```
app.use( express.json( { verify: ( req, res, buffer ) => { req.rawBody = buffer; } } ) );

```

This field is not available by default in Express. The `body` field available in Express contains the already processed data that cannot be used to generate the signature.

```
const crypto = require( 'crypto' );

const express = require( 'express' );
const app = express();

const API_SECRET = 'secret';

app.use( express.json( { verify: ( req, res, buffer ) => { req.rawBody = buffer; } } ) );

app.post( '/', ( req, res ) => {
    const signature = _generateSignature( req.method, req.url, req.headers[ 'x-cs-timestamp' ], req.rawBody );

    if ( signature !== req.headers[ 'x-cs-signature' ] ) {
        return res.sendStatus( 401 );
    }

    console.log( 'received webhook', req.body );
    res.sendStatus( 200 );
} );

app.listen( 9000, () => console.log( 'Node.js server started on port 9000.' ) );

function _generateSignature( method, url, timestamp, body ) {
    const hmac = crypto.createHmac( 'SHA256', API_SECRET );

    hmac.update( `${ method.toUpperCase() }${ url }${ timestamp }` );

    if ( body ) {
        hmac.update( body );
    }

    return hmac.digest( 'hex' );
}

```

<a id="cs/latest/examples/webhooks/webhooks-server-nodejs.html--usage">

### Usage

Start the server with:

```
node index.js

```

If the server is running on port `9000`, run ngrok with:

```
./ngrok http 9000

```

After this, you should see a `*.ngrok.io` URL. Copy the `*.ngrok.io` URL and paste it in the webhook configuration. You should be able to receive webhooks now.

<a id="cs/latest/examples/webhooks/webhooks-server-php.html">source file: "cs/latest/examples/webhooks/webhooks-server-php.html"</a>

## Webhooks server in PHP

This article presents a simple [webhooks server](#cs/latest/developer-resources/webhooks/server.html) example.

<a id="cs/latest/examples/webhooks/webhooks-server-php.html--dependencies">

### Dependencies

This example does not require any external PHP dependencies.  
However, for local development purposes, a tunneling service is required. This example uses [ngrok](https://ngrok.com/).

You can download ngrok here: <https://ngrok.com/download>.

<a id="cs/latest/examples/webhooks/webhooks-server-php.html--examples">

### Examples

Below are two examples of a webhooks server.

<a id="cs/latest/examples/webhooks/webhooks-server-php.html--example-without-checking-the-request-signature">

#### Example without checking the request signature

This is a very simple example, with the server logging the `body` from the request to the console. The `body` contains the complete [webhook information](#cs/latest/developer-resources/webhooks/overview.html--webhook-format) sent from CKEditor Cloud Services.

```
<?php

$body = file_get_contents('php://input');

$webhook = json_decode($body);

file_put_contents('php://stdout', 'Webhook received: ' . print_r($webhook, true) . "\r\n");

```

<a id="cs/latest/examples/webhooks/webhooks-server-php.html--example-with-checking-the-request-signature">

#### Example with checking the request signature

This example shows how to verify if the request was sent from the CKEditor Cloud Services servers  
and was [signed](#cs/latest/developer-resources/security/request-signature.html) with the correct [API secret](#cs/latest/developer-resources/security/api-secret.html).

Several variables are needed to generate and check the signature. The [API secret](#cs/latest/developer-resources/security/api-secret.html) is available in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or in the Management Panel for On-Premises, the rest of the parameters are in the request:

* `method`: `$_SERVER['REQUEST_METHOD']`
* `url`: `$_SERVER['REQUEST_URI']`
* `timestamp`: `$_SERVER['HTTP_X_CS_TIMESTAMP']`
* `body`: `file_get_contents('php://input')`

```
<?php

$apiSecret = 'your-api-secret';

$requestMethod = $_SERVER['REQUEST_METHOD'] ?? '';
$receivedHmac = $_SERVER['HTTP_X_CS_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_CS_TIMESTAMP'] ?? '';
$url = $_SERVER['REQUEST_URI'];
$body = file_get_contents('php://input');

$data = $requestMethod . $url . $timestamp . $body;
$hmac = hash_hmac('sha256', $data, $apiSecret);

$isValid = hash_equals($hmac, $receivedHmac);

if (!$isValid) {
    // Invalid webhook signature, ignore the request.
    die();
}

$webhook = json_decode($body);

file_put_contents('php://stdout', 'Webhook event received: ' . print_r($webhook, true) . "\r\n");

```

<a id="cs/latest/examples/webhooks/webhooks-server-php.html--usage">

### Usage

Save the above example file as `index.php` and start the server with:

```
php -S 127.0.0.1:9000

```

If needed, run ngrok with:

```
./ngrok http 9000

```

After this, you should see a `*.ngrok.io` URL. Copy the `*.ngrok.io` URL and paste it in the webhook configuration. You should be able to receive webhooks now.

<a id="cs/latest/faq/index.html">source file: "cs/latest/faq/index.html"</a>

## Cloud Services FAQ

<a id="cs/latest/faq/index.html--how-to-update-the-editor-bundle">

### How to update the editor bundle?

An **editor bundle** is the source code of a pre-configured and ready-to-use CKEditor 5, which is minified and built as a single file. To use the document storage, import and export or connection optimization features, you need to upload an exact copy of the editor file from your application to the CKEditor Cloud Services server.

Read more about an editor bundle [here](#cs/latest/guides/collaboration/editor-bundle.html).

To ensure data consistency, it is recommended to update the editor bundle every time there is a change in your editor.

For instructions on how to update the editor bundle, check out the [documentation](#cs/latest/guides/collaboration/editor-bundle.html--updating-the-editor-bundle).

<a id="cs/latest/faq/index.html--how-can-i-update-the-editor">

### How can I update the editor?

After updating CKEditor 5 in your frontend application you may receive the `Incompatible bundle version or engine version detected` error while connecting to a document. It means the document was created using an older version of the editor. In such a case, you need to create a new collaboration session to keep working with the document.

There is no way to edit a document using two or more different versions of the editor.

To create a new collaboration session, you can disconnect all users and reconnect after 24 hours. Alternatively, you can end the open collaboration session programmatically using our [REST API method](https://docs.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete).

<a id="cs/latest/faq/index.html--how-to-detect-an-incompatible-bundle-version">

### How to detect an incompatible bundle version?

To check the bundle version which was used to initialize an editing session, you can perform a request to our [REST API](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D~1details/get).

In the response you will receive `bundle_version` which can be compared with the current [bundle version](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle).

If the bundle versions are different, users will not be able to connect to the document using the new editor. In that case, you can [flush the collaboration session](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete), but keep in mind that flushing it will break the document for the users that are already connected with an old editor. You can check whether anyone is still connected using a [dedicated REST API method](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D~1users/get).

<a id="cs/latest/faq/index.html--how-to-restore-a-corrupted-document">

### How to restore a corrupted document?

Sometimes a document can get broken as a result of some invalid operations. They can be caused by custom plugins, using an invalid bundle version, etc. In such a case, you will receive an error saying `The document cannot be accessed in the current state. Some operations could not be saved properly`.

The only way to recover such a document is by restoring it to the latest working version via the [REST API endpoint](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D~1restore/put). This method will remove the operations that break the document and prevent it from saving.

<a id="cs/latest/faq/index.html--how-to-save-documents">

### How to save documents?

CKEditor Cloud Services provide 3 ways of saving documents. By default, our services do not store customer documents permanently. To do so, you need to enable [the document storage feature](#cs/latest/guides/collaboration/document-storage.html).

You can also store documents in your own storage by using our [REST API methods](#cs/latest/guides/collaboration/import-and-export.html).

The third option is to save a document directly from your frontend application with the help of [the autosave plugin](#cs/latest/guides/collaboration/introduction.html--the-autosave-plugin).

For more details, including a comparison of the available save methods, check out [our documentation](#cs/latest/guides/collaboration/introduction.html--saving-the-collaboration-data).

<a id="cs/latest/faq/index.html--how-to-export-the-content-of-a-document">

### How to export the content of a document?

As soon as the document is created, you can make a request to our REST API to fetch its content. As a result, you will receive an HTML with custom tags containing the data added by the plugins.

You can find more information about exporting document content in a [dedicated section](#cs/latest/guides/collaboration/import-and-export.html).

<a id="cs/latest/faq/index.html--how-to-create-a-document-programmatically">

### How to create a document programmatically?

By default, a document is created when the first user connects to it. However, you can import a document before any user connects to it by using some previously exported document content.

For more information about importing document content, check out [our documentation](#cs/latest/guides/collaboration/import-and-export.html).

<a id="cs/latest/faq/index.html--how-to-get-comments">

### How to get comments?

The content of the comments and their metadata are kept in a database. The document content contains tags with comment IDs referencing the data in the database.

You can fetch the content of the chosen comment by performing a request to our [REST API](https://help.cke-cs.com/api/v5/docs#tag/Comments/paths/~1comments~1%7Bcomment%5Fid%7D/get). It is also possible to [get all comments in the given document](https://help.cke-cs.com/api/v5/docs#tag/Comments/paths/~1comments/get).

<a id="cs/latest/faq/index.html--how-to-get-suggestions">

### How to get suggestions?

Suggestions are embedded in a given document’s content, within dedicated tags. The database contains only the metadata, such as a suggestion’s state, its author, etc.

You can fetch suggestion metadata by performing a request to our [REST API](https://help.cke-cs.com/api/v5/docs#tag/Suggestions/paths/~1suggestions~1%7Bsuggestion%5Fid%7D/get).

<a id="cs/latest/faq/index.html--how-to-remove-all-the-data-from-a-given-environment">

### How to remove all the data from a given environment?

CKEditor Cloud Services [keeps some of the data in a persistent database](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data). However, all of this data is wiped out when removing a given environment.

Instructions on how to remove an environment can be found in a [dedicated section](#cs/latest/developer-resources/environments/environments-management.html--removing-an-environment).

All billing data stays untouched after such an operation, the monitoring data is removed automatically after 30 days.

<a id="cs/latest/faq/index.html--how-to-resend-a-webhook">

### How to resend a webhook?

In some cases, e.g. given an error in the webhook destination server, you may need to resend the webhook request manually. To perform such an operation, visit the `Webhooks` section in the [Customer Portal](https://portal.ckeditor.com) for SaaS or in the [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) for the On-Premises application.

From the list of created webhooks, select the one you are interested in. Next, on the list of requests, find the one you would like to resend. After selecting the request, click the `Resend the request` button, then confirm the operation in the following pop-up.

<a id="cs/latest/faq/index.html--are-identifiers-such-as-userid-documentid-etc-case-sensitive">

### Are identifiers such as `userId`, `documentId`, etc. case-sensitive?

All identifiers such as `userId`, `documentId`, etc. are case-sensitive. It means that e.g. `user1` and `User1` will be treated as two separate users. The only exception are CKEditor Collaboration Server On-Premises installations up to `4.12.1` for MySQL which are case-insensitive.

<a id="cs/latest/faq/index.html--migrating-from-case-insensitive-to-case-sensitive-ckeditor-collaboration-server-on-premises-installation">

#### Migrating from case-insensitive to case-sensitive CKEditor Collaboration Server On-Premises installation

If you would like to migrate from a case-insensitive installation, you can set up a fresh CKEditor Collaboration Server On-Premises installation on a version newer than `4.12.1` and use the [Export](https://help.cke-cs.com/api/v5/docs#tag/Documents/paths/~1documents~1%7Bsource%5Fdocument%5Fid%7D/post) and [Import](https://help.cke-cs.com/api/v5/docs#tag/Documents/paths/~1documents/post) REST API endpoints to migrate your content. A simple update of an old CKEditor Collaboration Server On-Premises above `4.12.1` does not convert the instance to be case-sensitive. Instead, a fresh installation with the migration process is required.

<a id="cs/latest/guides/basic-concepts/authorization.html">source file: "cs/latest/guides/basic-concepts/authorization.html"</a>

## Authorization

In this article, you will find authorization-related basic concepts used in the documentation.

CKEditor Cloud Services have a few authorization methods, and each of them is suited for a given communication way. To find more detailed information, please check the linked articles.

The diagram below shows what authorization methods are available and where given operations need to be performed.

<a id="cs/latest/guides/basic-concepts/authorization.html--api-secret">

### API Secret

An API secret is a secret used to generate a [signature](#cs/latest/developer-resources/security/request-signature.html) for requests made to the REST API.

It is also used to [verify webhooks requests](#cs/latest/developer-resources/webhooks/overview.html--security).

API secrets can be [managed through the Customer Portal, or through the Management Panel in case of On-premises installations](#cs/latest/developer-resources/security/api-secret.html--api-secrets-management).

<a id="cs/latest/guides/basic-concepts/authorization.html--access-key">

### Access Key

An Access Key is a key used to [generate signed tokens](#cs/latest/developer-resources/security/token-endpoint.html).  
Access Keys are generated in [the Customer Portal or in the Management Panel in case of On-premises installations](#cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials).

<a id="cs/latest/guides/basic-concepts/authorization.html--token-endpoint">

### Token endpoint

An endpoint created by a customer which returns a token. It needs to be created by customers and placed in the customers’ application. Thanks to that, a customer has the full ability to control the user data and privileges sent.

You can read more about the token endpoint in the [Token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) guide.

<a id="cs/latest/guides/basic-concepts/authorization.html--token">

### Token

It is returned from a Token endpoint. In the payload, it contains all user data and [roles and permissions](#cs/latest/developer-resources/security/roles.html) of the user to a given document. Based on a `sub` property of the token, the usage of the application is billed.

You can read more about tokens and their generation in a [dedicated section](#cs/latest/developer-resources/security/token-endpoint.html--token).

<a id="cs/latest/guides/basic-concepts/data-model.html">source file: "cs/latest/guides/basic-concepts/data-model.html"</a>

## Data models

In this article, you will get familiar with basic data structures mentioned in other articles. To find more detailed information, please check one of the linked articles.

The diagram below, shows how the mentioned data structures are organized and how are they related.

<a id="cs/latest/guides/basic-concepts/data-model.html--organization">

### Organization

Organization is the widest entity in a context of Cloud Services provided by CKSource. Organization groups environments created by a customer. Depending on a case, single customer can have multiple, totally independent, organizations.

For CKEditor Collaboration Server On-premises customers there is only one, default organization in a context of a single application installation, what is fully transparent while using the application.

<a id="cs/latest/guides/basic-concepts/data-model.html--environment">

### Environment

A single organization consist of multiple environments, which ensures logical data separation.

Data of each environment are still held in a single database, however there are encrypted using individual keys. It ensures that there are not any chances to fetch others environment’s data by accident. Webhooks, editor bundles, document storage and other features needs to be configured separately for each environment.

One of use-cases of having multiple environments are multiple stages of the application, e.g. “Development”, “Staging”, “QA” and “Production”.

For an On-premises installation it allows to create multitenant applications, where each end-customer utilizes separate set of data with separated secrets, keys and encryption.

Environments can be [managed through the Customer Portal, or through the Management Panel in case of On-premises installations](#cs/latest/guides/basic-concepts/management.html).

<a id="cs/latest/guides/basic-concepts/data-model.html--document">

### Document

Document is a set of data representing the most basic entity in a context of the CKEditor Collaboration Server. It is logical structure, which describes linked pieces of information. In the application it is identified by `documentId` or `channelId`. Each document can have comments, suggestions, revisions, etc., assigned to it.

Documents can be also managed through the [Documents API](https://help.cke-cs.com/api/docs#tag/Documents) in the [REST API](#cs/latest/developer-resources/apis/overview.html--ckeditor-cloud-services-restful-apis).

<a id="cs/latest/guides/basic-concepts/data-model.html--editingcollaboration-session">

### Editing/Collaboration session

While the real-time collaboration plugin connects to a specific document on a CKEditor Collaboration Server, a new editing session is created. The editing session in an instance of a document, which is held in a temporary memory, where all content changes from the editor are applied. Each user who connects to a single document, connects to the same editing session where all changes of content are propagated to all connected users.

An editing session can be initialized in a multiple ways, which are explained in [a dedicated section](#cs/latest/guides/collaboration/introduction.html--ways-of-initializing-the-collaboration-session-with-data).

24 hours after the last user disconnects, the editing session expires and it is removed from a temporary memory. The document content can be saved using various methods, depending on a use-case.

You can read more about saving documents [in a more detailed guide](#cs/latest/guides/collaboration/introduction.html--saving-the-collaboration-data).

Editing sessions can be managed using the [Collaboration API](https://help.cke-cs.com/api/v5/docs#tag/Collaboration) in the [REST API](#cs/latest/developer-resources/apis/overview.html--ckeditor-cloud-services-restful-apis).

<a id="cs/latest/guides/basic-concepts/editor-bundle.html">source file: "cs/latest/guides/basic-concepts/editor-bundle.html"</a>

## Editor bundle

An editor bundle is the source code of a pre-configured and ready-to-use CKEditor 5, which is minified and built as a single file. To use the [Server-side Editor API](#cs/latest/guides/collaboration/server-side-editor-api.html), [document storage](#cs/latest/guides/collaboration/document-storage.html), [import and export](#cs/latest/guides/collaboration/import-and-export.html), or [connection optimization](#cs/latest/guides/collaboration/connection-optimization.html) features, you need to upload an exact copy of the editor file from your application to the CKEditor Cloud Services server.

CKEditor Cloud Services uses your editor bundle to convert operations in the collaboration session into data. Thanks to this, CKEditor Cloud Services can ensure data consistency between users and the stored data. Furthermore, if your editor bundle is using some custom plugins that can output some custom data, it will be then properly handled by CKEditor Cloud Services.

Whenever you change something in your editor bundle or its configuration, you should update it on the CKEditor Cloud Services server, too. If the users use different versions of the editor than the one uploaded to the server, it may lead to data loss or even editor crashes.

More information and detailed instructions about using editor bundles can be found in a [dedicated section](#cs/latest/guides/collaboration/editor-bundle.html--building-the-editor-bundle).

<a id="cs/latest/guides/basic-concepts/management.html">source file: "cs/latest/guides/basic-concepts/management.html"</a>

## Management

CKEditor Cloud Services provides tools to manage [environments](#cs/latest/guides/basic-concepts/data-model.html--environment) and other features. These tools are provided in the form of a web application.

<a id="cs/latest/guides/basic-concepts/management.html--customer-portal">

### Customer Portal

A place where customers can manage their existing license subscriptions and products.

On-Premises subscribers will find credentials needed to pull Docker images there as well as license keys for their applications.

For SaaS users, it also provides a panel for managing [environments](#cs/latest/guides/basic-concepts/data-model.html--environment), [access keys](#cs/latest/guides/basic-concepts/authorization.html--access-key), [API secrets](#cs/latest/guides/basic-concepts/authorization.html--api-secret), etc. On-premises users can access this panel via the [Management Panel](#cs/latest/guides/basic-concepts/management.html--management-panel) for On-Premises.

The Customer Portal is available at [portal.ckeditor.com](https://portal.ckeditor.com/).

<a id="cs/latest/guides/basic-concepts/management.html--management-panel">

### Management Panel

This is where On-Premises users can manage their [environments](#cs/latest/guides/basic-concepts/data-model.html--environment), [access keys](#cs/latest/guides/basic-concepts/authorization.html--access-key), [API secrets](#cs/latest/guides/basic-concepts/authorization.html--api-secret), etc.

It can be found under the `/panel` path on the server where CKEditor Collaboration Server On-premises is running.

More information about the Management Panel in the On-premises version can be found in a [dedicated guide](#cs/latest/onpremises/cs-onpremises/management.html).

<a id="cs/latest/guides/ckeditor-ai/actions.html">source file: "cs/latest/guides/ckeditor-ai/actions.html"</a>

## Actions

Transform specific text content with focused operations such as grammar fixing and translation. Actions are single-purpose tools that take content in, apply a transformation, and return the result.

Unlike conversations, actions do not remember previous interactions. Each action is independent and focused on a single task.

**When to use Actions vs Reviews:** Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone). Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content.

<a id="cs/latest/guides/ckeditor-ai/actions.html--available-actions">

### Available Actions

<a id="cs/latest/guides/ckeditor-ai/actions.html--system-actions">

#### System Actions

CKEditor AI provides built-in system actions for common content transformation tasks:

* **Fix Grammar** – Catch and correct spelling mistakes, grammar errors, and punctuation issues.
* **Improve Writing** – Enhance clarity, flow, and overall writing quality.
* **Continue Writing** – Complete unfinished sentences, paragraphs, or entire documents.
* **Make Longer** – Expand content with more detail, examples, and explanations.
* **Make Shorter** – Condense lengthy text while keeping the essential information.
* **Adjust Tone** – Change writing style to casual, professional, friendly, or confident.
* **Translate** – Convert content between languages with proper cultural context.

<a id="cs/latest/guides/ckeditor-ai/actions.html--custom-actions">

#### Custom Actions

In addition to system actions, you can create custom actions tailored to your specific use cases. Custom actions allow you to define specialized content transformations using your own prompts to control AI behavior.

Unlike system actions that use predefined identifiers, custom actions use a unified endpoint where you define the transformation behavior through a prompt parameter.

<a id="cs/latest/guides/ckeditor-ai/actions.html--key-features">

### Key Features

Each action is independent and does not require conversation context. Actions use streaming output with Server-Sent Events for real-time feedback as results are generated.

<a id="cs/latest/guides/ckeditor-ai/actions.html--api-examples">

### API Examples

<a id="cs/latest/guides/ckeditor-ai/actions.html--grammar-fix-example">

#### Grammar Fix Example

```
POST /v1/actions/system/fix-grammar/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--writing-improvement-example">

#### Writing Improvement Example

```
POST /v1/actions/system/improve-writing/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>The system works by processing data through various algorithms to produce results.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--content-expansion">

#### Content Expansion

```
POST /v1/actions/system/make-longer/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>Artificial intelligence is transforming the way we work.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--content-condensation-example">

#### Content Condensation Example

```
POST /v1/actions/system/make-shorter/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>Artificial intelligence, which is a rapidly evolving field of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence, is transforming the way we work across various industries and sectors.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--tone-adjustment-example">

#### Tone Adjustment Example

```
POST /v1/actions/system/make-tone-casual/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>We regret to inform you that your request cannot be processed at this time.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--translation-example">

#### Translation Example

```
POST /v1/actions/system/translate/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>Hello, how are you today?</p>"
    }
  ],
  "args": {
    "language": "Spanish"
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/actions.html--custom-action-example">

#### Custom Action Example

```
POST /v1/actions/custom/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p>The company's Q4 revenue was $2.5M, representing a 15% increase YoY.</p>"
    }
  ],
  "prompt": "Convert financial abbreviations to full words (e.g., 'YoY' to 'year-over-year', 'Q4' to 'fourth quarter') to make the text more accessible to general audiences.",
  "model": "agent-1",
  "outputFormat": "html"
}

```

Custom actions require the `ai:actions:custom` permission in your JWT token.

<a id="cs/latest/guides/ckeditor-ai/actions.html--streaming-responses">

### Streaming Responses

Actions use Server-Sent Events (SSE) for real-time streaming results. See the [Streaming Responses guide](#cs/latest/guides/ckeditor-ai/streaming.html) for detailed implementation information.

<a id="cs/latest/guides/ckeditor-ai/actions.html--api-reference">

### API Reference

For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see:

* **[Actions API Reference](https://ai.cke-cs.com/docs#tag/Actions)** – Full documentation for system and custom actions endpoints.
* **[Complete API Documentation](https://ai.cke-cs.com/docs)** – Interactive API reference with all CKEditor AI endpoints.

<a id="cs/latest/guides/ckeditor-ai/actions.html--related-features">

### Related Features

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – For interactive discussions with document analysis and context.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – For content quality analysis and improvement suggestions.
* [Streaming Responses](#cs/latest/guides/ckeditor-ai/streaming.html) – For implementing real-time review suggestions.

<a id="cs/latest/guides/ckeditor-ai/conversations.html">source file: "cs/latest/guides/ckeditor-ai/conversations.html"</a>

## Conversations

Conversations allow you to exchange multiple messages with AI that maintains them in its context. Conversations can be extended by external context sources like websites or files, and have the ability to refer to editor content and suggest modifications.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--key-features">

### Key Features

Upload PDFs, Word docs, and images for the AI to read and understand. Ask questions about specific sections and get intelligent answers. The AI extracts text while preserving structure from PDFs, maintains formatting context from Word documents, parses web content from HTML files, and processes images with OCR and object recognition.

Each conversation builds on previous messages, so the AI keeps track of your entire discussion and any files you have shared. You can mix documents, images, web links, and text in one conversation, and the AI connects information across all formats. Enable web search for real-time research while keeping your conversation context.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--example-product-launch-workflow">

#### Example: Product Launch Workflow

1. **Upload product spec** → _“What are the key features for marketing?”_
2. **Add competitor analysis** → _“How do we compare to competitors?”_
3. **Reference blog post** → _“Write a press release using this blog post and our competitive advantages”_
4. **Include brand guidelines** → _“Match our brand voice and key messaging”_

The AI remembers everything you have shared and builds on it throughout your conversation.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--advanced-features">

### Advanced Features

<a id="cs/latest/guides/ckeditor-ai/conversations.html--web-search">

#### Web Search

Enable real-time web search to access current information during conversations. The AI searches the web for relevant content, processes and analyzes the results, and integrates findings into responses while maintaining conversation context. Configure via the `webSearch` capability in API requests.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--reasoning">

#### Reasoning

Enable step-by-step reasoning to see the AI’s problem-solving process. The AI breaks down complex queries into logical steps, considers multiple approaches, and can revise conclusions when new information emerges. Configure via the `reasoning` capability in API requests.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--api-reference">

### API Reference

For complete API documentation including endpoints, parameters, and response schemas, see the [REST API documentation](https://ai.cke-cs.com/docs#tag/Conversations).

<a id="cs/latest/guides/ckeditor-ai/conversations.html--api-examples">

### API Examples

<a id="cs/latest/guides/ckeditor-ai/conversations.html--create-a-conversation">

#### Create a Conversation

```
POST /v1/conversations
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "id": "my-conversation-123",
  "title": "Document Analysis Session",
  "group": "research"
}

```

<a id="cs/latest/guides/ckeditor-ai/conversations.html--upload-a-document">

#### Upload a Document

Before you can reference documents in conversations, you need to upload them first:

```
POST /v1/conversations/my-conversation-123/documents
Content-Type: multipart/form-data
Authorization: Bearer <your-token>

file: [your-document.pdf]

```

Response:

```
{
  "id": "doc-123",
}

```

You can see how to upload other resources, including web resources and files using [REST API documentation](https://ai.cke-cs.com/docs#tag/Conversations).

<a id="cs/latest/guides/ckeditor-ai/conversations.html--send-a-message-with-context">

#### Send a Message with Context

```
POST /v1/conversations/my-conversation-123/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Analyze the attached document and provide a summary of the key points",
  "model": "agent-1",
  "content": [
    {
      "type": "document",
      "id": "doc-123"
    }
  ],
  "capabilities": {
    "webSearch": {},
    "reasoning": {}
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/conversations.html--send-a-message-with-multiple-context-types">

#### Send a Message with Multiple Context Types

```
POST /v1/conversations/my-conversation-123/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Compare the attached document with the information from the web resource",
  "model": "agent-1",
  "content": [
    {
      "type": "document",
      "id": "doc-123"
    },
    {
      "type": "web-resource",
      "id": "web-123"
    },
  ],
  "capabilities": {
    "webSearch": {}
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/conversations.html--streaming-responses">

### Streaming Responses

Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the [Streaming Responses guide](#cs/latest/guides/ckeditor-ai/streaming.html) for detailed implementation information and code examples.

<a id="cs/latest/guides/ckeditor-ai/conversations.html--related-features">

### Related Features

* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – Content quality analysis and improvement suggestions.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – Content transformation and batch processing.
* [AI Models](#cs/latest/guides/ckeditor-ai/models.html) – Choosing the right AI model for your conversations.
* [Streaming Responses](#cs/latest/guides/ckeditor-ai/streaming.html) – Implementing real-time conversation features.

<a id="cs/latest/guides/ckeditor-ai/document-processing.html">source file: "cs/latest/guides/ckeditor-ai/document-processing.html"</a>

## Document Processing

Transform entire HTML documents with free-form AI instructions — no editor instance, no streaming, no conversation state.

Send a document and a natural-language prompt to a single REST endpoint. The API returns the modified document and a summary of what changed as synchronous JSON. Built for server-side integrations, content pipelines, and backend automation.

<a id="cs/latest/guides/ckeditor-ai/document-processing.html--how-it-works">

### How It Works

The endpoint accepts two fields:

* **`document`** – The HTML content to process.
* **`prompt`** – A natural language instruction describing the desired change.

The AI applies the instruction and returns:

* **`document`** – The complete modified HTML document.
* **`summary`** – A concise explanation of what was changed and why.

The response preserves HTML structure, attributes and CSS classes unless the instruction explicitly  
requires modifying them.

<a id="cs/latest/guides/ckeditor-ai/document-processing.html--when-to-use-this">

### When to use this

Document Processing is designed for server-side workflows where content flows through your systems without a user in an editor:

* **CMS publish hooks** — fix grammar or adjust tone before content goes live
* **Sequential processing** — apply the same instruction to contracts, policies, or templates one document at a time
* **Pipeline steps** — translate or summarize as one step in a larger workflow
* **SaaS personalization** — adapt templates before delivering to end users
* **AI agent tooling** — expose as a tool in your own AI agents or MCP servers

<a id="cs/latest/guides/ckeditor-ai/document-processing.html--api-example">

### API Example

```
POST /v1/documents/process
Content-Type: application/json
Authorization: Bearer <your-token>

{
"document": "<p>The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic
curtain.</p>",
"prompt": "Fix all grammar and spelling errors"
}

```

<a id="cs/latest/guides/ckeditor-ai/document-processing.html--api-reference">

### API Reference

For complete endpoint documentation, request/response schemas, authentication details, and error codes, see:

* **[Document processing API Reference](https://ai.cke-cs.com/docs#tag/Document-processing)** – Full documentation for the document processing endpoint.
* **[Complete API Documentation](https://ai.cke-cs.com/docs)** – Interactive API reference with all CKEditor AI endpoints.

<a id="cs/latest/guides/ckeditor-ai/document-processing.html--related-features">

### Related Features

* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – Transform content with predefined or custom operations.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – Analyze documents and get per-element improvement suggestions.
* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – Interactive discussions with document context.

<a id="cs/latest/guides/ckeditor-ai/limits.html">source file: "cs/latest/guides/ckeditor-ai/limits.html"</a>

## Limits

Understand the limits that ensure fair usage, optimal performance, and cost control across all CKEditor AI features.

<a id="cs/latest/guides/ckeditor-ai/limits.html--overview">

### Overview

CKEditor AI implements various limits to ensure fair usage, optimal performance, and cost control. These include rate limits for API requests, context limits for content size and processing, model-specific constraints, and file restrictions.

<a id="cs/latest/guides/ckeditor-ai/limits.html--rate-limits">

### Rate Limits

Rate limits control the frequency of API requests to prevent abuse and ensure service stability. The service implements limits on API requests, token usage, web search, and web scraping requests per minute. All rate limits are applied at both organization level (higher limits) and individual user level (lower limits) to ensure fair usage.

<a id="cs/latest/guides/ckeditor-ai/limits.html--context-limits">

### Context Limits

Context limits control how much content can be attached to conversations to ensure AI models can process all information effectively. These limits vary by model based on their specific capabilities and processing requirements.

<a id="cs/latest/guides/ckeditor-ai/limits.html--file-limits">

#### File Limits

Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation.

<a id="cs/latest/guides/ckeditor-ai/limits.html--model-specific-file-limits">

##### Model-specific file limits

Anthropic and agent models may use files up to 5MB each.

<a id="cs/latest/guides/ckeditor-ai/limits.html--context-optimization-tips">

#### Context Optimization Tips

Compress images and split large documents into smaller sections. Use text formats (TXT or MD) over PDF when possible for better processing. Attach only relevant files to conversations and provide document summaries for very large files.

<a id="cs/latest/guides/ckeditor-ai/limits.html--model-specific-limits">

### Model-Specific Limits

Different AI models have varying capabilities and limitations that affect context processing. Each model has different context window sizes that determine how much content can be processed. Models have response timeouts, file processing timeouts, web resource timeouts, and streaming response limits. All models include content moderation for inappropriate content, safety checks, and moderation response time limits.

<a id="cs/latest/guides/ckeditor-ai/limits.html--next-steps">

### Next Steps

* [Learn about AI Models](#cs/latest/guides/ckeditor-ai/models.html) for model-specific limitations.
* [Set up Permisssions](#cs/latest/guides/ckeditor-ai/permissions.html) to control user access.
* [Explore Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) for context management.
* [API Documentation](https://ai.cke-cs.com/docs) – Complete API reference for CKEditor AI.

<a id="cs/latest/guides/ckeditor-ai/models.html">source file: "cs/latest/guides/ckeditor-ai/models.html"</a>

## AI Models

Choose the right AI model for your needs. CKEditor AI provides access to leading AI models, each optimized for different use cases and performance requirements.

<a id="cs/latest/guides/ckeditor-ai/models.html--recommended-agent-models">

### Recommended: Agent Models

CKEditor AI provides agent models that automatically select the optimal AI model for your specific task, balancing speed, quality, and cost. Agent models are internally registered and versioned, with the exact model name varying by compatibility version, for example, `agent-1`.

**Benefits:**

* Automatic optimization for each request type.
* No need to understand individual model capabilities.
* Cost-effective routing to appropriate models.
* Continuous improvement as new models become available.

For most use cases, we recommend using the agent model appropriate for your compatibility version and letting the system handle model selection.

<a id="cs/latest/guides/ckeditor-ai/models.html--available-models">

### Available Models

| Model ID          | Name              | Provider  | Web Search | Reasoning |
| ----------------- | ----------------- | --------- | ---------- | --------- |
| agent-1           | Agent             | Agent     | Yes        | Yes       |
| gpt-5             | GPT-5             | OpenAI    | Yes        | Yes       |
| gpt-5.1           | GPT-5.1           | OpenAI    | Yes        | Yes       |
| gpt-5.2           | GPT-5.2           | OpenAI    | Yes        | Yes       |
| gpt-5.4           | GPT-5.4           | OpenAI    | Yes        | Yes       |
| gpt-5.4-mini      | GPT-5.4 Mini      | OpenAI    | Yes        | Yes       |
| gpt-4.1           | GPT-4.1           | OpenAI    | Yes        | No        |
| gpt-5-mini        | GPT-5 Mini        | OpenAI    | Yes        | Yes       |
| gpt-4.1-mini      | GPT-4.1 Mini      | OpenAI    | Yes        | No        |
| claude-4-5-sonnet | Claude 4.5 Sonnet | Anthropic | Yes        | Yes       |
| claude-4-6-sonnet | Claude 4.6 Sonnet | Anthropic | Yes        | Yes       |
| claude-4-5-haiku  | Claude 4.5 Haiku  | Anthropic | Yes        | Yes       |
| gemini-3-1-pro    | Gemini 3.1\. Pro  | Google    | Yes        | Yes       |
| gemini-2-5-flash  | Gemini 2.5 Flash  | Google    | Yes        | Yes       |
| gemini-3-flash    | Gemini 3 Flash    | Google    | Yes        | Yes       |

All models support conversations, reviews, and actions. Each model has specific limits for prompt length, conversation length, file handling, and other constraints. For current specifications and availability in your environment, query the `/v1/models` endpoint.

<a id="cs/latest/guides/ckeditor-ai/models.html--how-model-selection-works">

### How Model Selection Works

The platform supports models from major AI providers including OpenAI, Google, and Anthropic. Each model has different capabilities, performance characteristics, and limitations. The system automatically handles model selection, failover, and optimization to provide the best experience for your use case.

<a id="cs/latest/guides/ckeditor-ai/models.html--model-compatibility-versions">

### Model Compatibility Versions

Model Compatibility Versioning identifies sets of LLMs compatible with specific service versions. This ensures your application continues to work reliably as new models are added or existing models are updated. Each service version has a specific set of compatible models, with older versions remaining available for existing integrations and new models added to newer service versions, providing clear upgrade paths.

<a id="cs/latest/guides/ckeditor-ai/models.html--how-it-works">

#### How It Works

1. **Versioned Model Sets** – Each compatibility version represents a curated list of models available at a specific API version.
2. **Stable Integrations** – Your application continues working even as new models are added to the platform.
3. **Controlled Upgrades** – Upgrade to newer compatibility versions when ready to test and support new models.
4. **Backward Compatibility** – Older versions remain supported, allowing you to upgrade on your schedule.

<a id="cs/latest/guides/ckeditor-ai/models.html--checking-compatibility">

#### Checking Compatibility

You can check which models are available for your service version:

```
GET /v1/models/1

```

Currently, there is only one compatibility version available: `1`. This version includes all currently supported models. As the platform evolves, new compatibility versions will be introduced to provide curated model sets for different API versions.

Example response:

```
{
  "items": [
    {
      "id": "gpt-4o",
      "name": "GPT-4o",
      "provider": "OpenAI",
      "allowed": false,
      "capabilities": {
        "webSearch": {
          "enabled": false
        },
        "reasoning": {
          "enabled": false
        }
      }
    },
    {
      "id": "gemini-2-5-pro",
      "name": "Gemini 2.5 Pro",
      "provider": "Google",
      "allowed": true,
      "capabilities": {
        "webSearch": {
          "enabled": true,
          "allowed": true
        },
        "reasoning": {
          "enabled": true,
          "allowed": false
        }
      }
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/models.html--model-capabilities">

### Model Capabilities

All models support conversations, reviews, and actions. Some models also support web search and reasoning capabilities.

<a id="cs/latest/guides/ckeditor-ai/models.html--web-search">

#### Web Search

Real-time web search with source attribution for current events, fact verification, and research. May increase response time.

When enabled, models can search the web before generating responses to access up-to-date information beyond their training data. You can enable web search by including `"webSearch": {}` in the `capabilities` object of your API request.

<a id="cs/latest/guides/ckeditor-ai/models.html--reasoning">

#### Reasoning

A step-by-step reasoning for complex problem solving, mathematical reasoning, and logical analysis. Available for select models (support varies by model and compatibility version).

**Important:** Some models have reasoning **always enabled** and cannot disable it. For these models:

* The reasoning capability is always active during inference.
* You cannot turn reasoning off via the API.

To determine if a model has always-on reasoning, check the API response when listing models. Models with mandatory reasoning will indicate this in their capability structure.

<a id="cs/latest/guides/ckeditor-ai/models.html--web-scraping">

#### Web Scraping

Extract and process content from web pages for analysis and summarization.

<a id="cs/latest/guides/ckeditor-ai/models.html--model-limitations">

### Model Limitations

<a id="cs/latest/guides/ckeditor-ai/models.html--file-processing-limits">

#### File Processing Limits

Files are limited to 7MB each (PDF, DOCX, PNG, JPEG, Markdown, HTML, Plain text). You can upload up to 100 files per conversation with a total size limit of 30MB. PDF files are limited to 100 pages total across all PDFs in a conversation.

<a id="cs/latest/guides/ckeditor-ai/models.html--model-specific-file-limits">

##### Model-specific file limits

Anthropic and agent models may use files up to 5MB each.

<a id="cs/latest/guides/ckeditor-ai/models.html--content-moderation">

#### Content Moderation

All models include moderation for inappropriate content, harmful instructions, personal information, copyrighted material, misinformation, sensitive topics, and security threats.

<a id="cs/latest/guides/ckeditor-ai/models.html--model-descriptions">

#### Model Descriptions

Model descriptions returned by the API are provided in English and may be updated over time to reflect model improvements or capability changes.

<a id="cs/latest/guides/ckeditor-ai/models.html--translation-and-localization">

#### Translation and Localization

If your application requires translated model descriptions, maintain a translation map in your code keyed by `model.id`, with fallback to the English description from the API for unknown models. This allows new models to work immediately while you add translations at your own pace.

<a id="cs/latest/guides/ckeditor-ai/models.html--model-deprecation">

#### Model Deprecation

Models scheduled for removal will include a `removal` field with an ISO 8601 date (e.g., `"removal": "2025-11-17T00:00:00.000Z"`). When a model is removed, API requests will fail with error code `MODEL_NOT_FOUND` and the models endpoint will stop returning that particular model.

<a id="cs/latest/guides/ckeditor-ai/models.html--api-examples">

### API Examples

<a id="cs/latest/guides/ckeditor-ai/models.html--model-selection">

#### Model Selection

```
POST /v1/conversations/my-conversation-123/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Analyze this document and provide insights",
  "model": "agent-1",
  "content": [
    {
      "type": "document",
      "id": "doc-1234567890123"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/models.html--capability-configuration">

#### Capability Configuration

```
POST /v1/conversations/my-conversation-123/messages
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "prompt": "Research the latest developments in AI",
  "model": "gpt-4o",
  "capabilities": {
    "webSearch": {},
    "reasoning": {}
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/models.html--model-information">

#### Model Information

Get all available models for compatibility version `1`:

```
GET /v1/models/1
Authorization: Bearer <your-token>

```

Response:

```
{
  "items": [
    {
      "id": "agent-1",
      "name": "Agent",
      "provider": "Agent",
      "description": "Automatically selects the best model for speed, quality, and cost",
      "allowed": true,
      "capabilities": {
        "webSearch": {
          "enabled": true,
          "allowed": true
        },
        "reasoning": {
          "enabled": true,
          "allowed": true
        }
      },
      "limits": {
        "maxPromptLength": 30000,
        "maxConversationLength": 256000,
        "maxFiles": 100,
        "maxFileSize": 7000000,
        "maxTotalFileSize": 30000000,
        "maxTotalPdfFilePages": 100
      }
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/models.html--api-reference">

### API Reference

For complete documentation on model endpoints, compatibility versions, and capability schemas, see:

* **[Models API Reference](https://ai.cke-cs.com/docs#tag/Models)** – Full documentation for model listing and configuration.
* **[Complete API Documentation](https://ai.cke-cs.com/docs)** – Interactive API reference with all CKEditor AI endpoints.

<a id="cs/latest/guides/ckeditor-ai/models.html--related-features">

### Related Features

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – Use models in interactive AI discussions.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – Apply models to content analysis and improvement.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – Use models for content transformation tasks.

<a id="cs/latest/guides/ckeditor-ai/overview.html">source file: "cs/latest/guides/ckeditor-ai/overview.html"</a>

## Overview

CKEditor AI integrates AI-assisted authoring with rich-text editing. Users can interact through Actions, Reviews, or Conversations that can use relevant context from multiple sources.

<a id="cs/latest/guides/ckeditor-ai/overview.html--getting-started">

### Getting Started

New to CKEditor AI? Kick you adventure off with the [Quick Start guide](#cs/latest/guides/ckeditor-ai/quick-start.html) to set up your environment, generate access credentials, and make your first API call.

<a id="cs/latest/guides/ckeditor-ai/overview.html--ckeditor-ai-features">

### CKEditor AI features

* **[Conversations](#cs/latest/guides/ckeditor-ai/conversations.html)** – Interactive AI chats with history and persistent context.
* **[Reviews](#cs/latest/guides/ckeditor-ai/reviews.html)** – Content analysis and proofreading, optimized for larger content.
* **[Actions](#cs/latest/guides/ckeditor-ai/actions.html)** – Fast, stateless operations for specific tasks.
* **[Document Processing](#cs/latest/guides/ckeditor-ai/document-processing.html)** — Send HTML + a natural-language instruction, get back the modified document and a summary of changes. Synchronous JSON. Experimental.
* **[MCP support](#cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html)** – Connect to MCP servers to extend AI capabilities with external tools. Available only in the [on-premises version](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html).

<a id="cs/latest/guides/ckeditor-ai/overview.html--architecture">

### Architecture

The following pages cover the system architecture.

* **[Models](#cs/latest/guides/ckeditor-ai/models.html)** – AI model selection, capabilities, and configuration.
* **[Streaming](#cs/latest/guides/ckeditor-ai/streaming.html)** – Real-time streaming of AI-generated responses.
* **[Permissions](#cs/latest/guides/ckeditor-ai/permissions.html)** – How to control user access to features.
* **[Limits](#cs/latest/guides/ckeditor-ai/limits.html)** – Rate limits, context size limits, and file restrictions.

<a id="cs/latest/guides/ckeditor-ai/overview.html--data-handling-and-security">

### Data Handling and Security

<a id="cs/latest/guides/ckeditor-ai/overview.html--regional-data-storage">

#### Regional Data Storage

All data stored by CKEditor AI follows the region settings of your CKEditor Cloud Services environment, ensuring compliance with data residency requirements and optimal performance for your geographic location.

<a id="cs/latest/guides/ckeditor-ai/overview.html--data-retention-policy">

#### Data Retention Policy

Conversation data is automatically deleted after 12 months of inactivity, including:

* all conversation messages and history,
* attached documents, files, and web resources,
* conversation metadata and settings.

<a id="cs/latest/guides/ckeditor-ai/overview.html--security">

#### Security

All data is encrypted in transit and at rest with end-to-end encryption. Conversations and attachments are stored in secure cloud infrastructure with fine-grained access control and comprehensive permission systems. [Audit Logs](#cs/latest/guides/system-security.html--audit-logs) are available through our Customer Portal and the API.

<a id="cs/latest/guides/ckeditor-ai/overview.html--ai-interaction-review">

#### AI Interaction Review

The SaaS version of CKEditor AI includes an AI interaction review setting that helps us improve response quality and diagnose issues. No customer data is ever used to train AI models. If this setting is enabled in the [Customer Portal](https://portal.ckeditor.com/), authorized CKEditor team members may review selected AI interactions for service improvement and troubleshooting.

**What may be reviewed**  
Selected AI interactions may include prompts, responses, and related content submitted to CKEditor AI features as part of a request.

CKEditor AI On-Premises does not allow sharing any data externally, so AI interaction review does not apply to On-premises deployments.

<a id="cs/latest/guides/ckeditor-ai/overview.html--on-premises-deployment">

### On-Premises Deployment

For organizations that need to run CKEditor AI within their own infrastructure, an on-premises version of the service is available. See the [CKEditor AI On-Premises documentation](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html) for details on deployment, configuration, and requirements.

<a id="cs/latest/guides/ckeditor-ai/overview.html--resources-and-support">

### Resources and Support

* **REST API Documentation**: <https://ai.cke-cs.com/docs> – Complete API reference for CKEditor AI.
* **Customer Support**: [Contact us](https://ckeditor.com/contact/) to get help from our support team or speak with sales.

<a id="cs/latest/guides/ckeditor-ai/permissions.html">source file: "cs/latest/guides/ckeditor-ai/permissions.html"</a>

## Permissions

You can control access to AI features, models, and capabilities based on user roles, subscription tiers, and organizational requirements.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--overview">

### Overview

The CKEditor AI permission system allows integrators to manage their users’ access to specific functionality. This enables control over AI features, models, and capabilities based on user roles, subscription tiers, or organizational requirements. Permissions provide flexible access control, role-based management, security, and cost control for premium models and capabilities.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--use-cases">

### Use Cases

For SaaS applications, users in different tiers might have access to different features. You can upgrade/downgrade users between tiers while preserving their data, control file type access where higher tiers can use more file types, manage model access where premium tiers can use more powerful models, and implement feature restrictions where basic tiers have limited functionality.

For enterprise systems with multiple roles, you can implement file upload restrictions to prevent certain roles from uploading confidential information, provide review-only access for some users, disable manual model selection for users unfamiliar with AI differences, and grant feature-specific access for editors, reviewers, and administrators.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--permission-format">

### Permission Format

Permissions are specified in the JWT token’s `auth.ai.permissions` claim as an array of permission strings. Each permission follows the format: `ai:<permission-type>:<permission-value>`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--admin-permissions">

#### Admin Permissions

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiadmin">

##### `ai:admin`

Grants full administrative access to the AI.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--model-permissions">

#### Model Permissions

Model permissions control which AI models users can access across all features.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aimodels">

##### `ai:models:*`

Wildcard permission grant access to all available models. This is the default setting for most users, but new, potentially expensive models become automatically available.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aimodelsprovider">

##### `ai:models:<provider>:*`

Access to all models from a specific provider. Examples: `ai:models:openai:*`, `ai:models:anthropic:*`, `ai:models:google:*`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aimodelsprovidermodel-name">

##### `ai:models:<provider>:<model-name>`

Access to a specific model from a provider. Examples: `ai:models:openai:gpt-5`, `ai:models:anthropic:claude-4-sonnet`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aimodelsagent-recommended">

##### `ai:models:agent` ⭐ **Recommended**

Allow users to use the agent-1 model for optimal performance. No need to manually select models; automatic optimization for performance and cost.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--conversation-permissions">

#### Conversation Permissions

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversations">

##### `ai:conversations:*`

Wildcard permission for all conversation-related features, including all conversation permissions below.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationsread">

##### `ai:conversations:read`

Access to chat interface and conversation history, including loading conversation lists, viewing messages, and accessing chat UI.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationswrite">

##### `ai:conversations:write`

Ability to create and modify conversations, including sending messages and creating/updating/deleting conversations. Requires both `read` and `write` permissions for full functionality.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationswebsearch">

##### `ai:conversations:websearch`

Enable web search capability in conversations.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationsreasoning">

##### `ai:conversations:reasoning`

Enable reasoning capability in conversations.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--context-permissions">

#### Context Permissions

Context permissions control which types of content can be attached to conversations.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationscontext">

##### `ai:conversations:context:*`

Access to all context sources, including all file types, web resources, and other context types.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationscontextfiles">

##### `ai:conversations:context:files:*`

Access to all supported file types, including PDF, DOCX, TXT, MD, PNG, JPEG, HTML.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationscontextfilesformat">

##### `ai:conversations:context:files:<format>`

Access to specific file formats. Examples:

* `ai:conversations:context:files:pdf`
* `ai:conversations:context:files:docx`
* `ai:conversations:context:files:png`
* `ai:conversations:context:files:jpg`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiconversationscontexturls">

##### `ai:conversations:context:urls`

Ability to add web URLs as context.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--actions-permissions">

#### Actions Permissions

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiactions">

##### `ai:actions:*`

Access to all action types, including custom and system actions.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiactionscustom">

##### `ai:actions:custom`

Ability to run custom actions with free-form prompts.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiactionssystem">

##### `ai:actions:system:*`

Access to all pre-defined system actions.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aiactionssystemaction-name">

##### `ai:actions:system:<action-name>`

Access to specific system actions. Examples:

* `ai:actions:system:improve-writing`
* `ai:actions:system:fix-grammar`
* `ai:actions:system:translate`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--reviews-permissions">

#### Reviews Permissions

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aireviews">

##### `ai:reviews:*`

Access to all review types, including custom and system reviews.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aireviewscustom">

##### `ai:reviews:custom`

Ability to run custom reviews with free-form prompts.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aireviewssystem">

##### `ai:reviews:system:*`

Access to all pre-defined system reviews.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--aireviewssystemreview-name">

##### `ai:reviews:system:<review-name>`

Access to specific system reviews. Examples:

* `ai:reviews:system:correctness`
* `ai:reviews:system:clarity`
* `ai:reviews:system:make-tone-professional`

<a id="cs/latest/guides/ckeditor-ai/permissions.html--permission-examples">

### Permission Examples

<a id="cs/latest/guides/ckeditor-ai/permissions.html--basic-user">

#### Basic User

```
{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:read",
        "ai:conversations:write",
        "ai:models:agent",
        "ai:conversations:context:files:pdf",
        "ai:conversations:context:files:docx"
      ]
    }
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/permissions.html--premium-user">

#### Premium User

```
{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:*",
        "ai:models:*",
        "ai:actions:system:*",
        "ai:reviews:system:*"
      ]
    }
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/permissions.html--enterprise-admin">

#### Enterprise Admin

```
{
  "auth": {
    "ai": {
      "permissions": [
        "ai:admin"
      ]
    }
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/permissions.html--restricted-user-review-only">

#### Restricted User (Review Only)

```
{
  "auth": {
    "ai": {
      "permissions": [
        "ai:reviews:system:correctness",
        "ai:reviews:system:clarity",
        "ai:models:gpt-4.1-mini"
      ]
    }
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/permissions.html--best-practices">

### Best Practices

<a id="cs/latest/guides/ckeditor-ai/permissions.html--permission-design">

#### Permission Design

Begin with minimal, specific permissions based on actual requirements. Use wildcards only for testing environments and power users who need comprehensive access. Gradually expand permissions based on user needs and usage patterns.

Avoid `ai:models:*` in production to prevent unexpected access to new expensive models. Use provider-specific permissions like `ai:models:openai:*` for better control, or specify exact models for maximum control. Start with common formats (PDF, DOCX, TXT, PNG, JPEG) and add specialized formats only when needed.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--error-handling">

### Error Handling

When a user lacks required permissions, the API returns a `403 Forbidden` error with the message “No permissions to the resource”. Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission.

<a id="cs/latest/guides/ckeditor-ai/permissions.html--next-steps">

### Next Steps

* [Learn about AI Models](#cs/latest/guides/ckeditor-ai/models.html) for model selection and capabilities.
* [Learn about Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) for interactive AI discussions.
* [Explore Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) for content improvement.
* [Discover Actions](#cs/latest/guides/ckeditor-ai/actions.html) for content transformation.
* [API Documentation](https://ai.cke-cs.com/docs) – Complete API reference for CKEditor AI.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html">source file: "cs/latest/guides/ckeditor-ai/quick-start.html"</a>

## Quick Start

The aim of this article is to get you up and running with CKEditor AI.

To start, follow the steps below:

* Sign up for one of our [self-service plans](https://ckeditor.com/pricing/), or [contact us](https://ckeditor.com/contact/) to purchase the CKEditor AI license.
* Generate your access credentials in the [Customer Portal](https://portal.ckeditor.com/).
* Write a script that generates one-time tokens for authorizing end users of your application in CKEditor Cloud Services (using access credentials created earlier).

All steps are explained in details below.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--get-the-ckeditor-ai-license">

### Get the CKEditor AI license

You can purchase CKEditor AI as an add-on to selected tiers of our self-service plans. You can find details on our [pricing page](https://ckeditor.com/pricing/).

You can also [contact us](https://ckeditor.com/contact/) directly if you would like to have a custom plan.

For testing purposes, you can sign up for the [free trial](https://portal.ckeditor.com/checkout?plan=free).

After signing up, you will receive access to the customer dashboard (Customer Portal).

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--log-in-to-the-customer-portal">

### Log in to the Customer Portal

Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Cloud environments”.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--create-token-endpoint">

### Create token endpoint

You now need to create a [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. This endpoint securely authorizes end users of your application to use CKEditor AI features based on their permissions and access rights.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--development-token-endpoint">

#### Development token endpoint

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The development token URL can be obtained in two simple steps:

1. From the list of environments, select the one you want to manage. To create a new environment, follow the [Environments management](#cs/latest/developer-resources/environments/environments-management.html--creating-a-new-environment) guide.
1. The development token URL is accessible at the bottom of this section:

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--simulating-specific-users">

##### Simulating specific users

The development token URL generates random user data by default from a pool of 10 predefined users. If you would like to specify a particular user for AI functionality, you may pass the user ID in the query string using:

* `sub` (Optional) – The unique ID of the user in your system.

**Example:** If your token URL is `https://17717-dev.cke-cs.com/token/dev/XXX`, you can connect as user with ID “13” using: `https://17717-dev.cke-cs.com/token/dev/XXX?sub=13`

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--extending-the-default-user-limit">

##### Extending the default user limit

You may need to extend the default limit of 10 development users. Add a `limit` query parameter to your dev token URL:

**Example:**

```
https://17717-dev.cke-cs.com/token/dev/XXX?limit=40

```

This URL provides tokens from a pool of 40 predefined users. After the 10th token, you will start paying for development users. The maximum allowed value for the limit parameter is 50, so the maximum number of paid users will be 40 with predefined users. Using your own generated user IDs may result in an unpredictable number of paid users.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--writing-your-own-token-endpoint">

#### Writing your own token endpoint

To write your own [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html), create access credentials for the selected environment by going to the “Access credentials” tab and clicking the “Create a new access key” button.

Read more in the [Creating access credentials](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--cloud-region">

### Cloud region

Cloud Services can [reside in either US or EU region or in both](#cs/latest/guides/saas-vs-on-premises.html--cloud-region). The region is set per subscription and cannot be changed for existing environments by the user. For Custom plan with multi-region, you can choose the region during environment creation. This topic is addressed in more detail in the [Environment management](#cs/latest/developer-resources/environments/environments-management.html--cloud-region) guide.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--api-integration">

### API Integration

All features are accessible through the REST API at `https://ai.cke-cs.com` with JWT authentication. For detailed API examples and implementation guides, see:

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – Interactive AI discussions and document analysis.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – Content improvement and quality analysis.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – Content transformation and batch processing.
* [Streaming](#cs/latest/guides/ckeditor-ai/streaming.html) – Real-time AI interactions.

[Complete API Documentation](https://ai.cke-cs.com/docs) – Full API reference for CKEditor AI

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--next-steps">

### Next Steps

Now that you made your first API call, explore the features:

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – Start with interactive AI discussions.
* [AI Models](#cs/latest/guides/ckeditor-ai/models.html) – Choose the right model for your use case.
* [Permissions](#cs/latest/guides/ckeditor-ai/permissions.html) – Set up user access control for production.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) – Add content improvement features.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – Implement content transformation.

<a id="cs/latest/guides/ckeditor-ai/quick-start.html--integration-with-ckeditor-5">

### Integration with CKEditor 5

CKEditor 5 includes built-in support for CKEditor AI features. To enable AI capabilities in your editor:

1. **Install the AI plugin** – Add the CKEditor AI plugin to your CKEditor 5 build
2. **Configure credentials** – Provide your Cloud Services token endpoint
3. **Customize features** – Choose which AI features to enable (conversations, reviews, actions)
4. **Set permissions** – Control user access through JWT token permissions

For detailed integration instructions, see the [CKEditor 5 AI Features documentation](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html).

<a id="cs/latest/guides/ckeditor-ai/reviews.html">source file: "cs/latest/guides/ckeditor-ai/reviews.html"</a>

## Reviews

Analyze large documents for quality improvements and professional standards. Reviews analyze your content and provide specific recommendations for grammar, style, clarity, and tone improvements.

**When to use Reviews vs Actions:** Use Reviews when you need to analyze entire documents for quality improvements and get suggestions without automatically changing the content. Use Actions when you need to transform specific text content (fix grammar, translate, adjust tone).

<a id="cs/latest/guides/ckeditor-ai/reviews.html--available-reviews">

### Available Reviews

<a id="cs/latest/guides/ckeditor-ai/reviews.html--system-reviews">

#### System Reviews

CKEditor AI provides built-in system reviews for comprehensive content analysis:

* **Correctness** – Fix grammar, spelling, and factual errors.
* **Clarity** – Improve sentence structure, word choice, and logical flow.
* **Readability** – Enhance paragraph structure, transitions, and reading level.
* **Length Optimization** – Expand or condense content while preserving key information.
* **Tone Adjustment** – Modify tone to casual, direct, friendly, confident, or professional styles.
* **Translation** – Translate content between languages with cultural adaptation.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--custom-reviews">

#### Custom Reviews

In addition to system reviews, you can create custom reviews tailored to your specific content quality standards and editorial guidelines. Custom reviews allow you to define specialized analysis criteria using your own prompts to control the review behavior.

Unlike system reviews that use predefined identifiers, custom reviews use a unified endpoint where you define the analysis behavior through a prompt parameter.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--key-features">

### Key Features

Reviews use streaming output with Server-Sent Events for real-time feedback as suggestions are generated. Each review type is optimized for specific improvement tasks, providing consistent, high-quality analysis of text structure, style, and quality.

Reviews provide specific, actionable recommendations for content improvement.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--api-examples">

### API Examples

<a id="cs/latest/guides/ckeditor-ai/reviews.html--basic-grammar-review-example">

#### Basic Grammar Review Example

```
POST /v1/reviews/system/correctness/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">The norhtern lights dence across the polar skies, painting ribbons of green and purple light that ripple like a cosmic curtain.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/reviews.html--clarity-improvement-example">

#### Clarity Improvement Example

```
POST /v1/reviews/system/clarity/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">The system works by processing data through various algorithms to produce results.</p>"
    }
  ]
}

```

<a id="cs/latest/guides/ckeditor-ai/reviews.html--tone-adjustment-example">

#### Tone Adjustment Example

```
POST /v1/reviews/system/make-tone-casual/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">We regret to inform you that your request cannot be processed at this time.</p>"
    }
  ],
  "args": {
    "language": "casual"
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/reviews.html--translation-review">

#### Translation Review

```
POST /v1/reviews/system/translate/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">Hello, how are you today?</p>"
    }
  ],
  "args": {
    "language": "Spanish"
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/reviews.html--custom-review-example">

#### Custom Review Example

```
POST /v1/reviews/custom/calls
Content-Type: application/json
Authorization: Bearer <your-token>

{
  "content": [
    {
      "type": "text",
      "content": "<p data-id=\"p1\">Our product is really good and customers love it because it has many features.</p>"
    }
  ],
  "prompt": "Review the text for vague language and generic claims. Suggest specific, concrete alternatives that would make the content more credible and informative.",
  "model": "agent-1"
}

```

Custom reviews require the `ai:reviews:custom` permission in your JWT token.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--streaming-responses">

### Streaming Responses

Reviews use Server-Sent Events (SSE) for real-time streaming results. See the [Streaming Responses guide](#cs/latest/guides/ckeditor-ai/streaming.html) for detailed implementation information.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--api-reference">

### API Reference

For complete endpoint documentation, request/response schemas, authentication details, and additional parameters, see:

* **[Reviews API Reference](https://ai.cke-cs.com/docs#tag/Reviews)** – Full documentation for system and custom reviews endpoints.
* **[Complete API Documentation](https://ai.cke-cs.com/docs)** – Interactive API reference with all CKEditor AI endpoints.

<a id="cs/latest/guides/ckeditor-ai/reviews.html--related-features">

### Related Features

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) – For interactive discussions with document analysis and context.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html) – For content transformation and batch processing.
* [Streaming Responses](#cs/latest/guides/ckeditor-ai/streaming.html) – For implementing real-time review suggestions.

<a id="cs/latest/guides/ckeditor-ai/streaming.html">source file: "cs/latest/guides/ckeditor-ai/streaming.html"</a>

## Streaming

Real-time AI interactions using Server-Sent Events (SSE) for immediate feedback and progressive content generation.

<a id="cs/latest/guides/ckeditor-ai/streaming.html--overview">

### Overview

CKEditor AI services use Server-Sent Events (SSE) to provide real-time streaming responses. This allows you to see AI-generated content as it is being created, providing immediate feedback and enabling interactive experiences.

<a id="cs/latest/guides/ckeditor-ai/streaming.html--sse-event-types">

### SSE Event Types

Different AI services provide different types of streaming events. For service-specific event details, see:

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html--streaming-responses) – Interactive AI discussions with text streaming, web search sources, and reasoning.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html--streaming-responses) – Content improvement suggestions and review progress.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html--streaming-responses) – Content transformations and action progress.

<a id="cs/latest/guides/ckeditor-ai/streaming.html--basic-implementation">

### Basic Implementation

Here is the standard pattern for consuming SSE streams:

```
const response = await fetch('/v1/your-endpoint', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    // Your request payload
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));

      // Handle different event types
      // See service-specific guides for detailed event handling:
      // - Conversations: text-delta, source, reasoning, modification-delta
      // - Reviews: review-delta, review-metadata
      // - Actions: modification-delta, action-metadata

      switch (data.event) {
        case 'error':
          // Handle errors
          console.error('Error:', data.data.message);
          break;
        default:
          // Handle all other events
          console.log('Event:', data.event, data.data);
      }
    }
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/streaming.html--event-handling-patterns">

### Event Handling Patterns

For detailed event handling examples specific to each service, see:

* [Conversations](#cs/latest/guides/ckeditor-ai/conversations.html--streaming-responses) – Text streaming, web search sources, reasoning, and document modifications.
* [Reviews](#cs/latest/guides/ckeditor-ai/reviews.html--streaming-responses) – Review suggestions and progress tracking.
* [Actions](#cs/latest/guides/ckeditor-ai/actions.html--streaming-responses) – Content transformations and action progress.

<a id="cs/latest/guides/ckeditor-ai/streaming.html--error-handling">

### Error Handling

Always handle errors gracefully:

```
if (data.event === 'error') {
  const error = data.data;
  console.error('Streaming error:', error.message);

  // Show user-friendly error message
  showErrorMessage(error.message);

  // Optionally retry or fallback
  if (error.retryable) {
    setTimeout(() => retryRequest(), 1000);
  }
}

```

<a id="cs/latest/guides/ckeditor-ai/streaming.html--progress-tracking">

### Progress Tracking

Use metadata events to show progress. For service-specific progress tracking examples, see [Review progress and status information](#cs/latest/guides/ckeditor-ai/reviews.html).

<a id="cs/latest/guides/ckeditor-ai/streaming.html--api-reference">

### API Reference

For complete documentation on streaming endpoints, event schemas, and error codes, see:

* **[Complete API Documentation](https://ai.cke-cs.com/docs)** – Interactive API reference with streaming implementation details.
* **[Conversations API](https://ai.cke-cs.com/docs#tag/Conversations)** – Streaming events for conversations.
* **[Reviews API](https://ai.cke-cs.com/docs#tag/Reviews)** – Streaming events for reviews.
* **[Actions API](https://ai.cke-cs.com/docs#tag/Actions)** – Streaming events for actions.

<a id="cs/latest/guides/ckeditor-ai/streaming.html--next-steps">

### Next Steps

* [Learn about Conversations](#cs/latest/guides/ckeditor-ai/conversations.html) for interactive AI discussions.
* [Explore Reviews](#cs/latest/guides/ckeditor-ai/reviews.html) for content improvement.
* [Discover Actions](#cs/latest/guides/ckeditor-ai/actions.html) for content transformation.

<a id="cs/latest/guides/collaboration/access-control.html">source file: "cs/latest/guides/collaboration/access-control.html"</a>

## Access control

<a id="cs/latest/guides/collaboration/access-control.html--overview">

### Overview

Depending on the application’s use case, a need may occur to restrict access to particular capabilities of working with the documents. The CKEditor Collaboration Server provides a feature which allows to set specific privileges to a specific document for a particular user. The feature is a part of the [token](#cs/latest/developer-resources/security/token-endpoint.html--token-payload) returned from the [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html). Thanks to that, the privileges are fully controlled by the application.

To make the managing of basic privileges easier, the CKEditor Collaboration Server provides three predefined roles: `reader`, `commentator` and `writer`. The roles have been described in more detail in the dedicated [roles section](#cs/latest/developer-resources/security/roles.html--roles) of the Security guide. In case of need to create more specific roles, the CKEditor Collaboration Server allows to set particular privileges, which have been described in the [Roles and permissions](#cs/latest/developer-resources/security/roles.html--permissions) guide.

Keep in mind that privileges and roles are set separately for each user, so the logic of picking the right role or privileges must be implemented as a part of the [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) inside of the backend application.

<a id="cs/latest/guides/collaboration/access-control.html--examples">

### Examples

<a id="cs/latest/guides/collaboration/access-control.html--restricting-document-editing">

#### Restricting document editing

Let’s assume there is a need to allow the user with ID `user284` to only read documents named with the `-read` suffix. However, they should also be able to edit documents with the `-edit` suffixes. The example below shows what the [token](#cs/latest/developer-resources/security/token-endpoint.html--token-payload) should look like for such a case:

```
{
    aud: 'your_environment_id',
        sub: 'user284',
        auth: {
                collaboration: {
                        '*-read': {
                                'permissions': [
                                        'document:read',
                                        'comment:read'
                        	]
                        },
                        '*-edit': {
                                'permissions': [
                                        'document:read',
                                        'comment:read',
                                        'document:write',
                                        'comment:write'
                                ]
                        }
                }
        }
}

```

In the example above, the `*-read` and `*-edit` properties represent patterns of document/channel IDs, so for the document/channel with ID `my-document-read`, the user with ID/sub `user284` will be able only to read the document. However, for a document/channel with ID `my-document-edit` they will also be able to edit it.

With these permissions, the user with ID `user284` will not be able to open any other document than the documents with matching `*-edit` or `*-read` document/channel ID patterns.

<a id="cs/latest/guides/collaboration/access-control.html--removing-comment-threads">

#### Removing comment threads

There can also arise a need to create a user with privileges to remove whole comment threads created by other users in the whole environment. The user with ID `user284` should be able to add comments as well as remove whole comment threads from a document, but should not be able to edit document content.

```
{
    aud: 'your_environment_id',
        sub: 'user284',
        auth: {
                collaboration: {
                        '*': {
                                'permissions': [
                                        'document:read',
                                        'comment:read',
                                        'comment:write',
                                        'comment:admin'
                        	]
                        }
                }
        }
}

```

In the presented example, the user with ID `user284` can read all documents in the environment and comment them. Moreover, the user has the privilege to remove comment threads created by any other user, but they still cannot edit nor remove particular comments.

<a id="cs/latest/guides/collaboration/access-control.html--next-steps">

### Next steps

[Read how to implement, configure and use the token endpoint](#cs/latest/developer-resources/security/token-endpoint.html).  
[Read complete guide on how to use user roles and privileges](#cs/latest/developer-resources/security/roles.html).

<a id="cs/latest/guides/collaboration/connection-optimization.html">source file: "cs/latest/guides/collaboration/connection-optimization.html"</a>

## Connection optimization

<a id="cs/latest/guides/collaboration/connection-optimization.html--overview">

### Overview

A need for optimization may arise in documents that are being edited for a long time. The optimization is based on compressing operations sent during the editing process. This speeds up the document loading time in the rich text editor.

CKEditor 5 performs lots of calculations during the processing of operations. This affects the document loading time because the browser resources are limited. Compressing operations on connecting means that instead of processing thousands of operations, the editor only needs to process a few of them.

<a id="cs/latest/guides/collaboration/connection-optimization.html--prerequisites">

### Prerequisites

There are two steps that need to be taken, before you can start using the feature:

1. Upload your editor bundle with the editor configuration to the CKEditor Cloud Services server. Refer to the [Editor bundle](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle) guide for more information.
2. Set the required [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion) property in the editor configuration. Refer to the [Editor configuration](#cs/latest/guides/collaboration/editor-bundle.html--editor-configuration) section of the editor bundle documentation for more details.

<a id="cs/latest/guides/collaboration/connection-optimization.html--enabling-the-connection-optimization-feature">

### Enabling the connection optimization feature

Follow the steps below to set up the connection optimization feature.

1. Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Your products > Cloud Services”.
2. From the list of available subscriptions in the dashboard choose the subscription that you want to manage and press the “Manage” link.
1. Select the environment where you want to enable the connection optimization feature.
1. Navigate to the “Feature configuration” tab.
1. Switch on the feature in the “Collaboration > Connection optimization” section.

<a id="cs/latest/guides/collaboration/connection-optimization.html--usage">

### Usage

After you complete the steps above, the connection optimization feature will work automatically. CKEditor Cloud Services will periodically compress the operations, lowering the document loading time for your users.

<a id="cs/latest/guides/collaboration/connection-optimization.html--debugging">

### Debugging

If needed, it is possible to store all the collaboration data for debugging purposes. Thanks to this, our customer support team will be able to check the errors related to the connection optimization feature. However, please enable this option only when you are asked to do so by our customer support team.

<a id="cs/latest/guides/collaboration/connection-troubleshooting.html">source file: "cs/latest/guides/collaboration/connection-troubleshooting.html"</a>

## Connection troubleshooting

<a id="cs/latest/guides/collaboration/connection-troubleshooting.html--overview">

### Overview

The CKEditor Collaboration Server utilizes WebSockets connections to communicate with the CKEditor. WebSockets connections provide two-way communication between the editor and server. Such a connection is used to provide a real-time experience.

Another way CKEditor 5 communicates with external resources is by HTTPS connection. This mechanism is used to fetch a token from a token endpoint and upload and download images from CKBox service.

<a id="cs/latest/guides/collaboration/connection-troubleshooting.html--requirements">

### Requirements

* WebSockets (port 443)
* HTTPS (port 443)

<a id="cs/latest/guides/collaboration/connection-troubleshooting.html--possible-problems">

### Possible problems

<a id="cs/latest/guides/collaboration/connection-troubleshooting.html--restricted-websocket-connection">

#### Restricted WebSocket connection

In case when the WebSocket connection is not possible, the user will receive an error with `The number of initial connection attempt exceeded.` message.

In such a case, please verify whether the CKEditor Collaboration Server is available from the user’s browser. It can be done by opening the default page of the server: for SaaS visit [the Info Page](https://cke-cs.com/) page, for On-premises visit the `https://{your_domain}/panel` page and from the On-premises in version `4.5.0` the `https://{your_domain}/` page.

If the page is available but the error still occurs then there is a possibility that the WebSocket connection in blocked on the user’s device or network level.

The WebSocket connection may be blocked in a few ways:

User level:

* antivirus software
* firewalls
* older browsers or outdated browser versions

Network level:

* firewall
* router configuration
* Internet provider restrictions

Please verify that none of above things blocks the WebSocket connection. It is possible you will need to contact your system and network administrator. If the problem with WebSocket connection still occurs, feel free to [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/guides/collaboration/data-deletion.html">source file: "cs/latest/guides/collaboration/data-deletion.html"</a>

## Data deletion

<a id="cs/latest/guides/collaboration/data-deletion.html--overview">

### Overview

There are a few ways to different delete data from the server:

* [Collaboration REST API](https://help.cke-cs.com/api/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete) to delete only active collaboration session data.
* [Storage REST API](https://help.cke-cs.com/api/docs#tag/Storage/paths/~1storage~1%7Bdocument%5Fid%7D/delete) to delete document content from the document storage.
* [Suggestions REST API](https://help.cke-cs.com/api/v5/docs#tag/Suggestions/paths/~1suggestions/delete) to delete comments.
* [Comments REST API](https://help.cke-cs.com/api/v5/docs#tag/Comments/paths/~1comments/delete) to delete suggestions.

<a id="cs/latest/guides/collaboration/data-deletion.html--document-delete">

### Document delete

As you can see, all the above request deletes only part of the entire document. Depending on your needs, you may want to delete the entire document with all comments, suggestions, and more. To do this you can use [Documents REST API](https://help.cke-cs.com/api/docs#tag/Documents).

<a id="cs/latest/guides/collaboration/data-deletion.html--example">

#### Example

The example below has been prepared in `Node.js`.

1. Run the following commands

```
mkdir cs-document-delete-example && cd cs-document-delete-example && npm init -y && npm i axios && touch delete.cjs

```

1. Open `cs-document-delete-example/delete.cjs` and paste the following code snippet:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';

// Set document id
const documentId = 'my_document_id';

const deleteApiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/documents/${ documentId }`;

( async () => {
    await deleteDocument();

    async function deleteDocument( ) {
        try {
            const config = getConfig( 'DELETE', deleteApiEndpoint );
            const response = await axios.delete( deleteApiEndpoint, config );

            console.log( response.status );
        } catch ( error ) {
            console.log( error.message );
            console.log( error.response.data );
        }
    }
} )();

function getConfig( method, url ) {
    const CSTimestamp = Date.now();

    return {
        headers: {
            'X-CS-Timestamp': CSTimestamp,
            'X-CS-Signature': generateSignature( apiSecret, method, url, CSTimestamp )
        }
    };
}

function generateSignature( secret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', secret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    }

    return hmac.digest( 'hex' );
}

```

1. Update your credentials, and the `documentId` value in the code snippet with the id of an existing document.
2. Execute the `node delete.cjs` command.

After a successful response with a status code `204` from the delete request, the document with all resources will be deleted from the server.

<a id="cs/latest/guides/collaboration/data-deletion.html--troubleshooting">

### Troubleshooting

* We suggest enabling [Insight Panel](#cs/latest/developer-resources/monitoring/insights-panel.html), where you will find detailed logs from the whole process including exact reasons for any failed requests.

<a id="cs/latest/guides/collaboration/data.html">source file: "cs/latest/guides/collaboration/data.html"</a>

## Collaboration data

<a id="cs/latest/guides/collaboration/data.html--overview">

### Overview

The collaboration session starts when the first user connects to the document. The content is stored for as long as there is at least one user connected to the document. When the last user disconnects, the server will wait for 24 hours and then delete the temporary collaboration data.

One of the steps of integrating CKEditor 5 and Real-Time Collaboration with your application is providing saving the capabilities of the collaboration data to some permanent storage location and initializing the editor with new or saved content. There are several solutions to this. This guide will cover the available scenarios for getting and setting the collaboration data.

<a id="cs/latest/guides/collaboration/data.html--temporary-and-permanent-data">

### Temporary and permanent data

**CKEditor Cloud Services remove the collaboration session data 24 hours after the last user disconnects.** This includes any content in the editor that was created by the users. To preserve your content between collaboration sessions, you need to save it on your server or use our [Document storage](#cs/latest/guides/collaboration/document-storage.html) feature.  
Only operations performed on the document are stored during collaboration session lifetime. Operation is every update (document history) made during the editing session stored as an [object model](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fmodel%5Foperation%5Foperation-Operation.html).

Some of the data is stored permanently. This includes comments, suggestions, revisions, and user data. Thanks to this, comment content, timestamps, suggestion metadata, and user details will be stored between collaboration sessions and the users are not able to modify other users’ data.

When it comes to data removal, document content is permanently removed, while comments and suggestions are only marked as removed (e.g. when removing a comment or accepting a suggestion). The REST API for [comments](https://help.cke-cs.com/api/v5/docs#tag/Comments) and [suggestions](https://help.cke-cs.com/api/v5/docs#tag/Suggestions) also provides two types of removal - soft (the default one) and permanent (requires an explicit flag).

Deleting the environment permanently removes all the data associated with this environment.

<a id="cs/latest/guides/collaboration/data.html--recovery-snapshots">

### Recovery snapshots

When an editing session ends, a collaboration snapshot is created. It includes all the necessary data for debugging and retrieval of the document when required. The snapshot data is encrypted with a key unique for each environment. Snapshots and related data are permanently removed after 30 days.

<a id="cs/latest/guides/collaboration/data.html--use-cases">

#### Use cases

The collaboration snapshots feature can be helpful when solving hard to reproduce cases related to documents.  
For example:

* When data is stored on the user’s side relying on webhooks. When issue occurs with webhook delivery the data might be potentially lost.
* Issues related to the use of erroneous editor bundle.
* Issues related to operation corrupting the document.
* Other cases introducing irreversible changes to the document.

<a id="cs/latest/guides/collaboration/data.html--recovery-steps">

#### Recovery steps

In order to debug and/or retrieve document, the CKEditor team needs you to provide a zip containing these 3 files:

* The document snapshot `.json`
* The [editorBundle](#cs/latest/guides/collaboration/editor-bundle.html)
* The [config](#cs/latest/guides/collaboration/editor-bundle.html--editor-configuration)

To retrieve your document’s snapshot follow these steps:

1. Get a list of snapshots existing for the selected document. Use REST API [GET metadata endpoint](https://help.cke-cs.com/api/v5/docs#tag/Collaboration-snapshots/paths/~1collaboration-snapshots~1%7Bdocument%5Fid%7D~1metadata/get).
2. Use selected snapshot’s metadata to retrieve it and save it as `.json`. Use REST API [GET snapshots endpoint](https://help.cke-cs.com/api/v5/docs#tag/Collaboration-snapshots/paths/~1collaboration-snapshots~1%7Bdocument%5Fid%7D/get).
3. Get editorBundle. Use REST API [Get editor bundle endpoint](https://help.cke-cs.com/api/v5/docs#tag/Editor-bundles/paths/~1editors~1%7Bbundle%5Fversion%7D/get).
4. Get config. Use REST API [Get editor bundle config endpoint](https://help.cke-cs.com/api/v5/docs#tag/Editor-bundles/paths/~1editors~1%7Bbundle%5Fversion%7D~1config/get).
5. Send editorBundle, config and snapshot to our team.

When the CKEditor team retrieves operations from your document you will receive a file with your document’s content in HTML. Use the retrieved data to create [new editing session](#cs/latest/guides/collaboration/import-and-export.html--initiating-the-collaboration-session) by sending request to this [REST API endpoint](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations/post).

If you have any feedback regarding this feature, feel free to [contact us.](https://ckeditor.com/contact/)

<a id="cs/latest/guides/collaboration/data.html--comments-and-suggestions">

### Comments and suggestions

When a user adds a new comment or suggestion, in the editor’s content you will only find a reference to it – two HTML elements marking the start and the end of the suggestion or comment with an additional ID attribute. The rest of the data (the creation time, the user name, the content of the comment, etc.) is not visible in the editor data. In the case of Real-Time Collaboration plugins, the comments or suggestions metadata is sent to the Cloud Services server, where it can be securely stored and shared only with authorized users. Thanks to this approach, users cannot modify other users’ comments and suggestions.

Any comment or suggestion created during the collaboration session is assigned to the [document ID](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-channelid-configuration-property), where it was created. You cannot access its data with a different document ID. Similarly, you cannot access comments or suggestions created in a different environment, even if they are from the same organization or are on the same Collaboration Server On-Premises instance.

If you open a document containing comments or suggestions created in a collaboration session with a different `documentId` or in a different environment, it can result in an editor crash with one of the following errors:

* `track-changes-user-not-found`
* `Cannot find suggestion abc`
* `Comment thread abc not found`

The accepted or rejected suggestions and deleted comments are only marked as removed. This means that they can be restored via the REST API even after the collaboration session ends (24 hours after the last user disconnects). All restored metadata will be kept in the database as well. It is also possible to delete the comments and suggestions permanently using the REST API.

<a id="cs/latest/guides/collaboration/data.html--comment-archive">

### Comment archive

The comment archive feature requires storing additional data (context, attributes, etc.) of comment threads. Additional comment thread properties can be synchronized via comments REST-API, documents REST-API, or webhooks.

Starting with the v37.0.0 release of CKEditor 5 the comment thread data handling was slightly changed. Accepted comment threads are now treated as resolved and moved to the comment archive. Therefore, instead of `commentthread.removed` a new webhook called `commentthread.resolved` is triggered when a comment is moved to the archive.

When residing in an archive, a comment thread can be either:

* reopened – in such a case the `commentthread.reopened` webhook is triggered
* removed – in such a case the old `commentthread.removed` webhook is triggered

Moreover, 2 new webhooks were added:

* `commentthread.added` – triggered when comment thread is added, can contain added comments
* `commentthread.updated` – triggered when the comment thread is updated

<a id="cs/latest/guides/collaboration/data.html--rest-api">

#### Rest API

You can use Cloud Services REST API for CRUD operations on suggestions and comments. Example use cases of the suggestions and comments CRUD operations:

* transferring your existing content into Cloud Services databases,
* moving the suggestions or comments data between environments,
* moving the suggestions or comments data from one document to another,
* adding attributes to the suggestions or comments.
* … and more.

Refer to the [REST API documentation](https://help.cke-cs.com/api/v5/docs#tag/Comments) for more details.

<a id="cs/latest/guides/collaboration/data.html--webhooks">

#### Webhooks

CKEditor Cloud Services sends an HTTP POST request to a configured URL when specified [events](#cs/latest/developer-resources/webhooks/events.html) are triggered.

You can use comments and suggestions webhooks to:

* sync data from CKEditor Cloud Services servers with your databases,
* notify users when their comment is removed or gets an answer,
* notify users when the state of their suggestions changes,
* … and more.

Refer to the [Webhooks documentation](#cs/latest/developer-resources/webhooks/overview.html) for more details.

<a id="cs/latest/guides/collaboration/data.html--data-safety">

### Data safety

The data stored permanently by CKEditor Cloud Services is encrypted with a key that differs for each environment. Additionally, in most cases, the system uses identifiers instead of the data that originates from the users. CKEditor Cloud Services uses encryption to protect the communication between the user and the server and provides all communication interfaces using HTTPS or WSS protocols.

Refer to the [system security](#cs/latest/guides/system-security.html) section for more details.

<a id="cs/latest/guides/collaboration/document-copy.html">source file: "cs/latest/guides/collaboration/document-copy.html"</a>

## Document copy

<a id="cs/latest/guides/collaboration/document-copy.html--overview">

### Overview

The document copy feature allows users to copy an entire document from an active collaborative editing session or from [the document storage](#cs/latest/guides/collaboration/document-storage.html). The copy of the document can be then edited independently from the original document but will still contain all the comments and suggestions from the source document.

<a id="cs/latest/guides/collaboration/document-copy.html--prerequisites">

### Prerequisites

* An [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) needs to be uploaded.
* The source document needs to be created after uploading the editor bundle.

<a id="cs/latest/guides/collaboration/document-copy.html--usage">

### Usage

Copying a document means creating a new collaborative editing session using the document data from an already existing one on the CKEditor Collaboration Server. It is done by sending a request to `POST /documents/{source_document_id}` [method](https://help.cke-cs.com/api/docs#tag/Documents/paths/~1documents~1%7Bsource%5Fdocument%5Fid%7D/post) from our [REST API](https://help.cke-cs.com/api/docs).  
You can also use the endpoint to quickly create a copy of the document with comment and suggestion markers excluded without the need to modify the original document.

<a id="cs/latest/guides/collaboration/document-copy.html--example">

### Example

The example below has been prepared in `Node.js`.

1. Run the following commands

```
mkdir cs-copy-example && cd cs-copy-example && npm init -y && npm i axios && touch copy.js

```

1. Open `cs-copy-example/copy.js` and paste the following code snippet:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';
const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/documents/${ sourceDocumentId }`;

// Set source and target document id
const sourceDocumentId = 'my_document_id_source';
const targetDocumentId = 'my_document_id_target';

const body = {
    'target_document_id': targetDocumentId,
    'omit_comments': false,
    'omit_suggestions': false
};

const CSTimestamp = Date.now();
const config = {
   headers: {
      'X-CS-Timestamp': CSTimestamp,
      'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body )
   },
};

axios.post( apiEndpoint, body, config )
   .then( response => {
      console.log ( response.status );
   } ).catch( error => {
      console.log( error.message );
      console.log( error.response.data );
   } );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
   const url = new URL( uri );
   const path = url.pathname + url.search;
   const hmac = crypto.createHmac( 'SHA256', apiSecret );

   hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

   if ( body ) {
      hmac.update( Buffer.from( JSON.stringify( body ) ) );
   };

   return hmac.digest( 'hex' );
}

```

1. Update your credentials, the `sourceDocumentId` and the `targetDocumentId` values in the code snippet.
2. Execute the `node copy.js` command.

After a successful response with a status code `201`, you can open the editor with the same `targetDocumentId` as set in the snippet to see your copied content.

<a id="cs/latest/guides/collaboration/document-copy.html--troubleshooting">

### Troubleshooting

* In case of any operation while copying fails, e.g. fail while copying comments all data of a target document will be revoked. The data of the source document are not changed.
* We suggest enabling [Insight Panel](#cs/latest/developer-resources/monitoring/insights-panel.html), where you will find detailed logs from the copy process including exact reasons for any failed requests.

<a id="cs/latest/guides/collaboration/document-copy.html--more-info">

### More info

You will find more info in our [REST API documentation](https://help.cke-cs.com/api/docs#tag/Documents/paths/~1documents~1%7Bsource%5Fdocument%5Fid%7D/post).

<a id="cs/latest/guides/collaboration/document-import-and-export.html">source file: "cs/latest/guides/collaboration/document-import-and-export.html"</a>

## Document import and export

<a id="cs/latest/guides/collaboration/document-import-and-export.html--overview">

### Overview

The document import/export feature allows users to export, and import entire documents including:

* active collaborative editing session or stored content (if no active collaborative session exists and document storage is enabled),
* comments,
* suggestions,
* revision history.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--document-importexport-vs-collaboration-importexport">

### Document import/export vs. collaboration import/export

There is a similar [collaboration import and export](#cs/latest/guides/collaboration/import-and-export.html) feature which allows to import and export the data from the server. The main difference between those two is the fact that the document import/export allows for treating the document as one single resource providing the content, suggestions, comments, and more. The main benefit of this approach is the reduction of the number of requests that one has to perform to initialize and export all document data from the server. The second difference is that the [collaboration import and export](#cs/latest/guides/collaboration/import-and-export.html) feature only operates on an active collaboration session which means the data from the document storage will not be exported. What is more, the document export feature allows obtaining document content without the suggestions/comments markers.

For example, the document export/import workflow may be the following:

1. Import the document data or create a new collaborative editing session by connecting CKEditor 5.
2. Collaborate on the document – add and modify content, comments, and suggestions.
3. Export document data – save the exported document data in a client’s storage.
4. Remove document data.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--export-prerequisites">

### Export prerequisites

* An [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) needs to be uploaded.
* The exported document needs to exist in an active collaboration session or document storage.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--export-usage">

### Export usage

Exporting the entire document means returning the data from the active collaborative editing session or the document storage (if present), as well as all document-related data like comments and suggestions. It is done by sending a request to `GET /documents/{document_id}` from our [REST API](https://help.cke-cs.com/api/docs#tag/Documents).  
You can also use the feature to quickly export the content with the suggestion or comment markers excluded without the need to modify the original document.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--import-prerequisites">

### Import prerequisites

* An [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) needs to be uploaded.
* The target document should exist neither in a collaboration session nor in the document storage.
* Related comments and suggestions should not exist in the database.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--import-usage">

### Import usage

Importing the entire document means creating a new collaborative editing session using the document data from the request body including collaborative editing session data, comments, and suggestions. It is done by sending a request to `POST /documents` [REST API](https://help.cke-cs.com/api/docs#tag/Documents).

<a id="cs/latest/guides/collaboration/document-import-and-export.html--example">

### Example

The example below has been prepared in `Node.js`.

1. Run the following commands

```
mkdir cs-import-export-example && cd cs-import-export-example && npm init -y && npm i axios && touch importExport.cjs

```

1. Open `cs-import-export-example/importExport.cjs` and paste the following code snippet:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';

// Set document id
const documentId = 'my_document_id';

const importApiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/documents`;
const exportApiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/documents/${ documentId }`;

const importBody = {
    id: documentId,
    content: {
        bundle_version: '34.1.0',
        data: '<h2><comment-start name=\"e712d8a9d63d6f1201576ccb7c0f15a77:cd907\"></comment-start>Hello world<comment-end name=\"e712d8a9d63d6f1201576ccb7c0f15a77:cd907\"></comment-end> from <suggestion-start name=\"insertion:ed7c304a37913421ddc1d7950a144d41d:user-1\"></suggestion-start>example suggestion <suggestion-end name=\"insertion:ed7c304a37913421ddc1d7950a144d41d:user-1\"></suggestion-end>CKEditor 5!</h2>'
    },
    comments: [
        {
            id: 'e52d6b88056950a3d98ecd4f10053a74c',
            document_id: documentId,
            thread_id: 'e712d8a9d63d6f1201576ccb7c0f15a77',
            content: '<p>example comment</p>',
            attributes: {},
            updated_at: '2022-09-28T18:11:47.258Z',
            created_at: '2022-09-28T18:11:47.239Z',
            user: {
                id: 'user-1'
            },
            type: 1
        }
    ],
    suggestions: [
        {
            id: 'ed7c304a37913421ddc1d7950a144d41d',
            document_id: documentId,
            has_comments: false,
            attributes: {},
            created_at: '2022-09-28T18:11:23.726Z',
            author_id: 'user-1',
            state: 'open',
            type: 'insertion',
            requester_id: 'user-1'
        }
    ]
};

( async () => {
    await importDocument( importBody );

    const exportedData = await exportDocument();

    console.log( 'Exported data:' );
    console.log( exportedData );

    async function importDocument( body ) {
        try {
            const config = getConfig( 'POST', importApiEndpoint, body );
            const response = await axios.post( importApiEndpoint, body, config );

            console.log( response.status );

            return response.data;
        } catch ( error ) {
            console.log( error.message );
            console.log( error.response.data );
        }
    }

    async function exportDocument() {
        try {
            const config = getConfig( 'GET', exportApiEndpoint );
            const response = await axios.get( exportApiEndpoint, config );

            return response.data;
        } catch ( error ) {
            console.log( error.message );
            console.log( error.response.data );
        }
    }
} )();

function getConfig( method, url, body ) {
    const CSTimestamp = Date.now();

    return {
        headers: {
            'X-CS-Timestamp': CSTimestamp,
            'X-CS-Signature': generateSignature( apiSecret, method, url, CSTimestamp, body )
        }
    };
}

function generateSignature( secret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', secret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    }

    return hmac.digest( 'hex' );
}

```

1. Update your credentials and the `documentId` values in the code snippet.
2. Execute the `node importExport.cjs` command.

After a successful response with a status code `201` from the import request, you can open the editor with the same `documentId` as set in the snippet to see your imported content. Moreover, exported document content should be printed on the console.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--troubleshooting">

### Troubleshooting

* In case any operation during importing fails, e.g. fail while importing comments, all data of imported document will be revoked.
* We suggest enabling [Insight Panel](#cs/latest/developer-resources/monitoring/insights-panel.html), where you will find detailed logs from the whole process including exact reasons for any failed requests.

<a id="cs/latest/guides/collaboration/document-import-and-export.html--more-info">

### More info

You will find more info in our [REST API documentation](https://help.cke-cs.com/api/docs#tag/Documents).

<a id="cs/latest/guides/collaboration/document-storage.html">source file: "cs/latest/guides/collaboration/document-storage.html"</a>

## Document storage

<a id="cs/latest/guides/collaboration/document-storage.html--overview">

### Overview

The document storage feature allows you to permanently save the collaboration data in the CKEditor Cloud Services. When enabled, the documents are no longer [stored temporarily just for the duration of the document session lifetime](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data). Instead, the collaboration session data is saved permanently in the CKEditor Cloud Services server.

Data saved in the document storage consists of the following:

* **content** \- it is the full content of the edited document. It’s the equivalent of the results of calling [editor.getData()](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditor-Editor.html#function-getData).
* **operations** \- it is every document update (document history) made during the editing session stored as an [object model](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fengine%5Fmodel%5Foperation%5Foperation-Operation.html). The operations are stored in the compressed state.
* **version** \- the current version of the document. The version is determined based on the number of distinct operations performed.

When a user connects to a previously existing document for which the collaboration session has already expired, a new collaboration session will be initialized using the content stored in the document storage.

Your server is completely excluded from the responsibility of saving the document. You do not have to write any additional logic for getting the collaboration data, saving it in your database, and initializing the document with the previously saved data. These actions will be handled automatically by CKEditor Cloud Services.

<a id="cs/latest/guides/collaboration/document-storage.html--prerequisites">

### Prerequisites

To use the document storage feature, an editor with its configuration needs to be uploaded to the CKEditor Cloud Services server. Cloud Services is using your editor to generate the correct output data before saving and to initialize the collaboration session with previously stored data. Thanks to this approach, your custom plugins that could generate some custom data will also work correctly.

Two steps need to be taken before you can start using the feature:

1. Upload your editor bundle with the editor configuration to the CKEditor Cloud Services server. Refer to the [Editor bundle](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle) guide for more information.
2. Set the required [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion) property in the editor configuration. Refer to the [Editor configuration](#cs/latest/guides/collaboration/editor-bundle.html--editor-configuration) section of the editor bundle documentation for more details.

<a id="cs/latest/guides/collaboration/document-storage.html--enabling-the-document-storage-feature">

### Enabling the document storage feature

Follow the steps below to set up the document storage feature.

1. Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Your products > Cloud Services”.
1. From the list of available subscriptions in the dashboard choose the subscription that you want to manage and click the “Manage” link.
1. Select the environment where you want to enable the document storage feature. Create one if needed with the “Create new environment” button.
1. Navigate to the “Feature configuration” tab and switch on the feature in the “Storage > Document storage” section.

Remember that the document storage feature only works in the environment it was turned on for. If you use many environments, you need to enable the feature separately for each of these.

<a id="cs/latest/guides/collaboration/document-storage.html--usage">

### Usage

<a id="cs/latest/guides/collaboration/document-storage.html--initiating-the-collaboration-session">

#### Initiating the collaboration session

With the document storage enabled the sessions will be automatically created using the data stored in the CKEditor Collaboration Server databases. There are no additional actions required and initializing the editor with a `channelId` value will load the stored content.

The process for initializing the collaboration session is as follows:

1. A user wants to open a document with a given `channelId` and the editor starts to initialize.
2. The CKEditor Collaboration Server checks if the content was already stored in the document storage.
3. Editor initializes with the data of the stored document.

<a id="cs/latest/guides/collaboration/document-storage.html--saving-the-document">

#### Saving the document

After uploading the editor bundle and enabling the feature, the encrypted collaboration data will be saved automatically to the CKEditor Cloud Services database. There are several cases triggering the document save action:

* an operation in the document made by any of the users (once every 5 minutes),
* 1000 operations to the document made by the users,
* the last user disconnects from the collaboration session,
* a new document is created (either by the user or when a document is imported using the [REST API](#cs/latest/developer-resources/apis/overview.html)),
* a collaboration session is flushed using the [REST API](#cs/latest/developer-resources/apis/overview.html).

It is possible to trigger the document save action manually by using [REST API](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D~1save/put).

You can also import the document synchronously to the storage through [REST API](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage/post) for as long as there is no active collaboration session with the same ID.

<a id="cs/latest/guides/collaboration/document-storage.html--document-storage-webhooks">

#### Document storage webhooks

You can receive information about the processing of your document in the document storage in the form of webhook events. Refer to the [document storage events](#cs/latest/developer-resources/webhooks/events.html--document-storage) section for more details.

The document storage webhooks can be very useful when setting up the document storage. You can quickly verify that the documents are properly saved and there are no issues during this process.

Some use cases could require having a copy of the content in your application. To sync the content between the CKEditor Collaboration server and your application, you can use the [storage.document.saved](#cs/latest/developer-resources/webhooks/events.html--document-saved) webhook to receive a signal that a newer version of the document is available. This can trigger a REST API request to [fetch](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage~1%7Bdocument%5Fid%7D/get) the content from the CKEditor Collaboration Server and then store it in your database.

The recommended flow for keeping the documents in sync is as follows:

1. A user action or a REST API request triggers document storage saving.
2. The document content is saved in the CKEditor Collaboration Server databases.
3. The CKEditor Collaboration Server emits the `storage.document.saved` webhook, which includes the `channelId` property.
4. Once you receive the webhook, send a [GET /storage/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage~1%7Bdocument%5Fid%7D/get) request.
5. Store the content of the document in your database.

<a id="cs/latest/guides/collaboration/document-storage.html--document-management">

#### Document management

You can manage stored documents using the methods available from the [REST API](#cs/latest/developer-resources/apis/overview.html). The document storage methods available are:

* [POST /storage](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage/post) – imports the content of a document to the storage. It can be either HTML content or a stringified JSON structure for documents created by a [multi-root editor](#ckeditor5/latest/examples/builds/multi-root-editor.html). In the latter case, the keys are the root names and the values are the HTML content for a particular root.
* [GET /storage/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage~1%7Bdocument%5Fid%7D/get) – gets the content of a single document saved in the storage. It can be either HTML content or a stringified JSON structure for documents created by a [multi-root editor](#ckeditor5/latest/examples/builds/multi-root-editor.html). In the latter case, the keys are the root names and the values are the HTML content for a particular root.
* [GET /storage](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage/get) – gets the list of the document IDs that are saved in the storage.
* [DELETE /storage/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Storage/paths/~1storage~1%7Bdocument%5Fid%7D/delete) – deletes a single document from the storage.

<a id="cs/latest/guides/collaboration/document-storage.html--example">

### Example

Check an [example of an application that uses the document storage feature in Node.js and Express.js](#cs/latest/examples/collaboration-examples/storage-feature-nodejs.html).

Also, you can check the [CKEditor Cloud Services samples repository](https://github.com/ckeditor/cloud-services-samples), where you can find more examples.

<a id="cs/latest/guides/collaboration/document-storage.html--debugging">

### Debugging

If needed, it is possible to store all collaboration data for debugging purposes. Thanks to this, our customer support team will be able to check the errors related to the document storage feature. Please enable this option only when you are asked to do so by our customer support team.

<a id="cs/latest/guides/collaboration/editor-bundle.html">source file: "cs/latest/guides/collaboration/editor-bundle.html"</a>

## Editor bundle

<a id="cs/latest/guides/collaboration/editor-bundle.html--overview">

### Overview

An editor bundle is the source code of a pre-configured and ready-to-use CKEditor 5, which is minified and built as a single file. To use the [Server-side Editor API](#cs/latest/guides/collaboration/server-side-editor-api.html), [document storage](#cs/latest/guides/collaboration/document-storage.html), [import and export](#cs/latest/guides/collaboration/import-and-export.html), or [connection optimization](#cs/latest/guides/collaboration/connection-optimization.html) features, you need to upload an exact copy of the editor file from your application to the CKEditor Cloud Services server.

CKEditor Cloud Services uses your editor bundle to convert operations in the collaboration session into data. Thanks to this, CKEditor Cloud Services can ensure data consistency between users and the stored data. Furthermore, if your editor bundle is using some custom plugins that can output some custom data, it will be then properly handled by CKEditor Cloud Services.

Whenever you change something in your editor bundle or its configuration, you should update it on the CKEditor Cloud Services server, too. If the users use different versions of the editor than the one uploaded to the server, it may lead to data loss or even editor crashes.

<a id="cs/latest/guides/collaboration/editor-bundle.html--building-the-editor-bundle">

### Building the editor bundle

First, you need to create an editor bundle. You can follow our step-by-step [editor bundling guide](#cs/latest/examples/editor-bundle/advanced-editor-bundle-nodejs.html) or go with ready-to-use [editor bundle examples](#cs/latest/examples/editor-bundle/editor-bundle-nodejs.html).

<a id="cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle">

### Uploading the editor bundle

If you have already built your editor that meets the [requirements](#cs/latest/guides/collaboration/editor-bundle.html--building-the-editor-bundle), you can upload it to CKEditor Cloud Services together with the editor configuration. The editor upload process requires the use of the [POST /editors](https://help.cke-cs.com/api/v5/docs#tag/Editors/paths/~1editors/post) method from the Cloud Services REST API.

Every request made to the CKEditor Cloud Services REST API needs to have additional headers: `X-CS-Timestamp` and `X-CS-Signature`. Refer to the [request signature](#cs/latest/developer-resources/security/request-signature.html) guide for more details.

Three parameters are passed to the body of this method:

* `bundle` – The code of your minified editor passed as a string.
* `config` – This is the editor configuration that will be used by the editor in CKEditor Cloud Services. This should be the same config as used by the editor in your application, especially when it can alter the data output.
* `test_data` – This is the real document content generated by the editor you upload to the CKEditor Cloud Services server. It helps to detect if any of your custom plugins modify the document content incorrectly or if an invalid configuration has been passed. This parameter is optional but it is highly recommended to use it. You should make sure that your test data has been created using all the custom plugins you have implemented.

The body of the upload request should look like this:

```
{
    "bundle": "the content of editor bundle file",
    "config": {
        "cloudServices": {
            "bundleVersion": "unique_editor_bundle_version"
        },
        "removePlugins": [ "myCustomAutoSavePlugin" ],
        ... other config options
    },
    "test_data": "<p>example output from your editor</p>"
}

```

The `bundleVersion` property inside the `config.cloudServices` object is required.

<a id="cs/latest/guides/collaboration/editor-bundle.html--editor-configuration">

#### Editor configuration

The `bundleVersion` property set during an upload acts as a unique build identifier. It tells CKEditor Cloud Services which editor should be used when a user starts the collaboration session. You need to make sure that the editor configuration in your application also has the [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion) property and its value matches the editor uploaded to the CKEditor Cloud Services server. An example editor configuration with set `bundleVersion` looks like this:

```
return CKEditorCS
    .create( document.querySelector( '.collaboration-demo__editable' ), {
        cloudServices: {
            tokenUrl: 'TOKEN_URL',
            uploadUrl: 'UPLOAD_URL',
            webSocketUrl: 'WEBSOCKET_URL',
            bundleVersion: 'editor-1.0.0'
        },
        collaboration: {
            channelId: 'CHANNEL_ID'
        },
        toolbar: [
            // Toolbar items
        ],
        // Other config options
    } );

```

<a id="cs/latest/guides/collaboration/editor-bundle.html--multi-root-editor-builds">

#### Multi-root editor builds

For [**multi-root** editor builds](#ckeditor5/latest/examples/builds/multi-root-editor.html), an upload request body requires an additional `is_multi_root_editor` field set to `true`. The field indicates that the uploaded editor is a multi-root build. Additionally, the `test_data` property is expected to be a stringified JSON structure where the keys are the root names and the values are the HTML content for particular roots. Moreover, if you want to use the roots’ attributes you must provide example values for each root in the editor config.

```
{
    "bundle": "the content of a multi-root editor bundle file",
    "config": {
        "cloudServices": {
            "bundleVersion": "unique_multiroot_editor_bundle_version"
        },
        "removePlugins": [
            "myCustomAutoSavePlugin"
        ],
        "rootsAttributes": {
            "main": {
            "order": 1
            }
        },
        ... other config options
    },
    "test_data": "{\"header\":\"<p>Multi-root document header.</p>\",\"footer\":\"<p>Multi-root document footer.</p>\"}",
    "is_multi_root_editor": true
}

```

<a id="cs/latest/guides/collaboration/editor-bundle.html--example">

#### Example

Follow this example to learn how to properly upload the editor bundle to CKEditor Cloud Services. This example is using Node.js and `npm`, hence it is required to have these tools installed. It also assumes that you have already [built the editor bundle](#cs/latest/guides/collaboration/editor-bundle.html--building-the-editor-bundle). This example will continue using the files from the previous example.

1. In your terminal, use `cd` to get into the extracted folder and install the `axios` package with the `npm i axios` command.
2. Create a new `upload.js` file inside the extracted folder with the following content:

```
const crypto = require( 'crypto' );
const fs = require( 'fs' );
const path = require( 'path' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';

const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/editors/`;
const editorBundle = fs.readFileSync( path.resolve( './dist/editor.bundle.js' ) );

const body = {
    bundle: editorBundle.toString(),
    config: {
        cloudServices: {
            bundleVersion: 'editor-1.0.0' // Set a unique name for the uploaded bundle
        },
        toolbar: [
            // Toolbar items
        ],
        // Other config options
    }
};

const CSTimestamp = Date.now();
const axiosConfig = {
    headers: {
        'X-CS-Timestamp': CSTimestamp,
        'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body )
    }
};

axios.post( apiEndpoint, body, axiosConfig )
    .then( response => {
        console.log ( response.status );
    } ).catch( error => {
        console.log( error.message );
        console.log( error.response.data );
    } );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    }

    return hmac.digest( 'hex' );
}

```

Run the above code with the `node upload.js` command.

You should see the `201` status code in your console. You can run `node upload.js` once again to make sure that the bundle is already uploaded. In this case, you will get a 409 error with message `Editor editor-1.0.0 already exists`.

<a id="cs/latest/guides/collaboration/editor-bundle.html--updating-the-editor-bundle">

### Updating the editor bundle

As shown in the example above, it is not possible to overwrite an editor bundle on the CKEditor Cloud Services server. You may, however, encounter situations where you need to rebuild your editor, for example when you add a new plugin, update CKEditor 5 version or fix a bug in your custom plugin. You should follow these steps to start using a new editor bundle:

1. Rebuild your editor with the necessary changes to the configuration or plugins.
2. Upload the new editor bundle with the `bundleVersion` value being new and unique for your environment.
3. Update the [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion) in the editor configuration in your application to match the new value from step 2.
4. Wait for the active collaboration sessions [to be removed automatically](#cs/latest/guides/collaboration/data.html--temporary-and-permanent-data) or remove them manually using the [DELETE /collaborations/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete) from the CKEditor Cloud Services REST API.
5. Open the document in your new editor.

A collaboration session initiated with certain `bundleVersion` can be opened only by editors with the same `bundleVersion` value. Because of this you can not connect to the previously edited documents with the new editor, without reinitializing such collaboration session (steps 4 and 5).

<a id="cs/latest/guides/collaboration/import-and-export.html">source file: "cs/latest/guides/collaboration/import-and-export.html"</a>

## Collaboration import and export

<a id="cs/latest/guides/collaboration/import-and-export.html--overview">

### Overview

The process of saving the data of the document in an active collaboration session with multiple users can be challenging. A simple implementation using the [autosave plugin](#cs/latest/guides/collaboration/introduction.html--the-autosave-plugin) comes with some drawbacks. Another approach to initializing and saving collaboration data can solve most of them.

The import and export feature, based on the [REST API](#cs/latest/developer-resources/apis/overview.html), improves the process of synchronizing the data of the document which is saved in your database. When using this feature, the responsibility for saving the current document data will be transferred from the users to your server.

<a id="cs/latest/guides/collaboration/import-and-export.html--the-import-and-export-endpoints">

### The Import and Export endpoints

This feature utilizes two methods available from the REST API:

* Import a document – Use this endpoint to set the initial content and create a new collaboration session. This endpoint will not work if a collaboration session with a given `documentId` already exists.
* Export a document – Use this endpoint to fetch the content from an active collaboration session. In the response, you will get plain HTML or Markdown output from the editor (depending on the editor configuration), just like you would call `editor.getData()` on the client side. Exported document data may contain comments and/or suggestions markers if you are using corresponding plugins in your editor. To export a document without these markers use the [document import and export](#cs/latest/guides/collaboration/document-import-and-export.html) feature.

Follow this guide to learn how to properly set up and use this feature.

<a id="cs/latest/guides/collaboration/import-and-export.html--prerequisites">

### Prerequisites

To use the import and export feature, an editor with its configuration needs to be uploaded to the CKEditor Cloud Services server. Cloud Services uses your editor to generate the correct output during the export and to validate the input during the import. Thanks to this approach, your custom plugins that could generate some custom data will also work correctly.

Two steps need to be taken before you can start using the feature:

1. Upload your editor bundle with the editor configuration to the CKEditor Cloud Services server. Refer to the [Editor bundle](#cs/latest/guides/collaboration/editor-bundle.html--uploading-the-editor-bundle) guide for more information.
2. Set the required [bundleVersion](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html#member-bundleVersion) property in the editor configuration. Refer to the [Editor configuration](#cs/latest/guides/collaboration/editor-bundle.html--editor-configuration) section of the editor bundle documentation for more details.

<a id="cs/latest/guides/collaboration/import-and-export.html--usage">

### Usage

<a id="cs/latest/guides/collaboration/import-and-export.html--initiating-the-collaboration-session">

#### Initiating the collaboration session

Here is a recommended flow to successfully initialize an editing session using content stored in your database:

1. A user in your application that wants to open a document sends `channelId` (a new one or an already existing one) to your server.
2. Your server communicates with CKEditor Collaboration Server and uses the [GET /collaborations/{document\_id}/exists](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D~1exists/get) REST API endpoint to verify whether the session already exists.
3. Your server gets the document data from the database. This step should be skipped if the collaboration session already exists.
4. Your server initializes the collaboration session through the [POST /collaborations](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations/post) REST API endpoint. This step should be skipped if the collaboration session already exists.
5. Your server signals to the user that the session is ready to connect.
6. The editor initializes and connects the user to the collaboration session.

<a id="cs/latest/guides/collaboration/import-and-export.html--saving-document-data">

#### Saving document data

Depending on your use case, you may choose one or more of the following solutions to save the content from a collaboration session in your own database.

<a id="cs/latest/guides/collaboration/import-and-export.html--collaborationdocumentexported-webhook">

##### collaboration.document.exported webhook

We recommend using the [collaboration.document.exported](#cs/latest/developer-resources/webhooks/events.html--collaboration-session-exported) webhook for saving document data. This webhook is emitted when a collaboration session is removed and already contains the content of the session. This ensures that the saved content includes all changes made by users during document editing and that you receive the latest version of the document.

The recommended flow for using this webhook is as follows:

1. The collaboration session ends. You can either wait for it to end automatically 24 hours after the last user disconnects, or you can trigger it using the [DELETE /collaborations/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete) REST API endpoint.
2. CKEditor Collaboration Server emits the `collaboration.document.exported` webhook, which contains the content of the document and the `channelId` property.
3. Once you receive the data, store it in your database.

<a id="cs/latest/guides/collaboration/import-and-export.html--collaborationdocumentupdateexported-webhook">

##### collaboration.document.update.exported webhook

The above solution, which uses the `collaboration.document.exported` webhook, ensures that the latest possible version of the content is saved when the collaboration session ends. If you need frequent access to the current version of the content being edited in an active collaboration session, you can also use the [collaboration.document.update.exported](#cs/latest/developer-resources/webhooks/events.html--collaboration-session-update-exported) webhook. This webhook is periodically emitted during active editing sessions and after the last user disconnects from the collaboration session.

Here is the recommended flow for using this webhook:

1. The webhook is triggered by:  
  * adding an operation (once every 10 minutes) by the users,
  * adding 5000 operations by the users, or
  * the last user disconnecting from the collaboration session.
2. The `collaboration.document.update.exported` webhook, which contains the content of the document and the `channelId` property, is emitted from the CKEditor Collaboration Server.
3. After receiving the data, your server stores it in your database.

<a id="cs/latest/guides/collaboration/import-and-export.html--export-on-demand">

##### Export on demand

If the triggers defined for the `collaboration.document.exported` and `collaboration.document.update.exported` webhooks do not match your use case, and you want to create custom triggers to obtain collaboration data, you could send a [GET /collaborations/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/get) request to CKEditor Collaboration Server to receive the content of the active collaboration session.

The recommended flow for using export on demand looks as follows:

1. Some part of your application or a user action sends a request to your server with the `channelId` property.
2. Your server sends a [GET /collaborations/{document\_id}](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/get) request to CKEditor Collaboration Server to get the content of the collaboration session.
3. After receiving the data, your server stores it in your database.

<a id="cs/latest/guides/collaboration/import-and-export.html--rest-api-usage">

### REST API Usage

After successfully uploading your editor bundle to CKEditor Cloud Services you can start using the import and export feature. Every request made to Cloud Services REST API needs to have the following headers:

* `X-CS-Timestamp` – the value of this header will be used for the signature generation and validation and it is very important to use a unique value for every request to make sure that the generated signatures will be unique as well. This value needs to be a number. Good example of a timestamp is the current Unix time.
* `X-CS-Signature` – the value of this header is generated using a SHA-256 algorithm and is signed with the [API Secret](#cs/latest/developer-resources/security/api-secret.html). CKEditor Cloud Services are also generating signatures for every request and only accept the ones with a correct signature. Refer to the [Request signature guide](#cs/latest/developer-resources/security/request-signature.html) for more information.

Check an [example of an application that uses this mechanism in Node.js and Express.js](#cs/latest/examples/collaboration-examples/import-export-nodejs.html) or follow this guide for more details on the feature’s usage.

Also, you can check the [CKEditor Cloud Services samples repository](https://github.com/ckeditor/cloud-services-samples), where you can find more examples.

<a id="cs/latest/guides/collaboration/import-and-export.html--import-example">

#### Import example

Importing a document means creating a new collaboration session using the previously saved document data. It is based on sending a request from your server to CKEditor Cloud Services using the [POST /collaborations](https://docs.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations/post) REST API method with the required data in the body:

```
{
  "document_id": "your_document_id",
  "bundle_version": "your_editor_id",
  "data": "<p>document_content</p>"
}

```

At this point, CKEditor Cloud Services converts the document `data` sent in the request using the previously uploaded editor bundle with a set `bundle_version` and creates an active collaborative session for the `document_id`.

After this operation, users can connect to the newly created collaboration session and continue working on the loaded document.

This example is using node.js and `npm`. Make sure that you have these tools installed before you follow the next steps. This snippet assumes that you have already followed the steps from [Prerequisites](#cs/latest/guides/collaboration/import-and-export.html--prerequisites) section.

1. Run the following commands:

```
mkdir cs-import-example && cd cs-import-example
npm init -y && npm i axios

```

1. Create a new file named `import.js` in the `cs-import-example` folder with the following content:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';
const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/collaborations/`;

const body = {
    document_id: "document-1", // Set document_id of created collaboration session
    bundle_version: "bundleversion-1", // Use bundle_version from uploaded editor bundle
    data: "<p>Lorem Ipsum is <b>simply dummy</b> text of the printing and typesetting industry.</p>"
};

const CSTimestamp = Date.now();
const config = {
    headers: {
        'X-CS-Timestamp': CSTimestamp,
        'X-CS-Signature': generateSignature( apiSecret, 'POST', apiEndpoint, CSTimestamp, body )
    },
};

axios.post( apiEndpoint, body, config )
    .then( response => {
        console.log ( response.status );
    } ).catch( error => {
        console.log( error.message );
        console.log( error.response.data );
    } );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    };

    return hmac.digest( 'hex' );
}

```

1. Update your credentials, the `document_id` and `bundle_version` values in the code snippet.
2. Run the import with the `node import.js` command.

After a successful response with a status code `204` you can open the editor with the same `document_id` as set in the snippet to see your imported content. You can also check the content using the export method.

<a id="cs/latest/guides/collaboration/import-and-export.html--export-example">

#### Export example

Exporting a document means getting the current data of the document from an active collaboration session. It is based on sending a request from your server to CKEditor Cloud Services using the [GET /collaborations/{document\_id}](https://docs.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/get) REST API method.

At this point, using the previously loaded editor bundle, CKEditor Cloud Services converts an active collaboration session to the configured output form (HTML, Markdown, text etc.) which your server will receive in response to the request. Your server should save the received document data in the database.

This example is using node.js and `npm`. Make sure that you have these tools installed before you follow the next steps. This snippet assumes that you have already followed the steps from the [Prerequisites](#cs/latest/guides/collaboration/import-and-export.html--prerequisites) section.

1. Run the following commands:

```
mkdir cs-export-example && cd cs-export-example
npm init -y && npm i axios

```

1. Create a new file named `export.js` in the `cs-export-example` folder with the following content:

```
const crypto = require( 'crypto' );
const axios = require( 'axios' );

// Update with your credentials and application endpoint
const environmentId = 'txQ9sTfqmXUyWU5LmDbr';
const apiSecret = '4zZBCQoPfRZ7Rr7TEnGAuRsGgbfF58Eg0PA8xcLD2kvPhjGjy4VGgB8k0hXn';
const applicationEndpoint = 'https://33333.cke-cs.com';

const documentId = 'document-1'; // Set document_id of an active collaboration session
const apiEndpoint = `${ applicationEndpoint }/api/v5/${ environmentId }/collaborations/${ documentId }`;

const CSTimestamp = Date.now();
const config = {
    headers: {
        'X-CS-Timestamp': CSTimestamp,
        'X-CS-Signature': generateSignature( apiSecret, 'GET', apiEndpoint, CSTimestamp )
    },
};

axios.get( apiEndpoint, config )
    .then( response => {
        console.log ( response.data );
    } ).catch( error => {
        console.log( error.message );
        console.log( error.response.data );
    } );

function generateSignature( apiSecret, method, uri, timestamp, body ) {
    const url = new URL( uri );
    const path = url.pathname + url.search;
    const hmac = crypto.createHmac( 'SHA256', apiSecret );

    hmac.update( `${ method.toUpperCase() }${ path }${ timestamp }` );

    if ( body ) {
        hmac.update( Buffer.from( JSON.stringify( body ) ) );
    };

    return hmac.digest( 'hex' );
}

```

1. Update your credentials and the `documentId` value in the code snippet.
2. Run the export with the `node export.js` command.

You should see the content of an active collaboration session in your console.

<a id="cs/latest/guides/collaboration/introduction.html">source file: "cs/latest/guides/collaboration/introduction.html"</a>

## Introduction

<a id="cs/latest/guides/collaboration/introduction.html--saving-the-collaboration-data">

### Saving the collaboration data

This guide covers four separate methods of reading the content of a collaboration session to save it to some permanent storage using:

* **[The Cloud Services REST API](#cs/latest/guides/collaboration/introduction.html--export-using-the-cloud-services-rest-api)** – a server-side solution, where your server can send a request to Cloud Services Collaboration Server to receive the content of the edited document to store it in your database.
* **[Saving data with Webhooks](#cs/latest/guides/collaboration/introduction.html--saving-data-with-webhooks)** – a server-side solution, where your server receives requests (webhooks) with content of the documents when the collaboration sessions end.
* **[Document Storage](#cs/latest/guides/collaboration/introduction.html--document-storage)** – a Cloud Services solution, where the document data is permanently saved in the CKEditor Cloud Services server.
* **[The Autosave plugin](#cs/latest/guides/collaboration/introduction.html--the-autosave-plugin)** – a client-side solution, through which the users periodically send the content of the collaboration session to your server.

<a id="cs/latest/guides/collaboration/introduction.html--export-using-the-cloud-services-rest-api">

#### Export using the Cloud Services REST API

This mechanism, based on the [REST API](#cs/latest/developer-resources/apis/overview.html), was introduced as an alternative to the [autosave plugin](#ckeditor5/latest/features/autosave.html). It improves and simplifies the process of synchronizing the data of the document which is saved in your database.

Using this feature, the responsibility for saving the current document data will be transferred from collaborating users to your server. As a result, it is your server that gets the current content of the document from CKEditor Cloud Services.

Please compare the diagram showing the data workflow to notice the differences:

The number of requests is largely reduced – there is just one connection present between the CKEditor Cloud Services server and the client’s server. The whole responsibility of serving and storing the content is handled by server-server connection. The collaborator’s only role is content editing.

<a id="cs/latest/guides/collaboration/introduction.html--the-benefits-of-using-the-cloud-services-rest-api">

##### The benefits of using the Cloud Services REST API

* The user is sure to use the latest version of the document. There is no risk of [race condition](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-clouddocumentversion-property), data inconsistency or other problems related to document synchronization.
* Reduced number of requests to your server. Collaborating users no longer need to send the document data in time intervals.
* Increased communication security. The synchronization process takes place only between your server and the CKEditor Cloud Services server using an encrypted SSL connection and [request signatures](#cs/latest/developer-resources/security/request-signature.html).
* The process of saving the document data is independent of the network conditions in which the users work.
* The content in the collaboration session can be initialized by the client’s server.
* One export operation means only one document content which allows you to save some storage and get rid of minor changes to the document versions.

There are two types of export:

* [Document export](#cs/latest/guides/collaboration/document-import-and-export.html) – exports current collaboration session content or document storage content (if present and no current collaboration session exist), and all document-related data like comments and suggestions. Check out the [guide](#cs/latest/guides/collaboration/document-import-and-export.html) for the implementation details.
* [Collaboration export](#cs/latest/guides/collaboration/import-and-export.html) – exports only current collaboration session content. Check out the [guide](#cs/latest/guides/collaboration/import-and-export.html) for the implementation details.

<a id="cs/latest/guides/collaboration/introduction.html--saving-data-with-webhooks">

#### Saving data with webhooks

This approach is similar to REST API usage, but the main difference is the direction of the requests. With REST API export endpoints you send a request to the Cloud Services server and the server responds with the content of the edited documents. When using webhooks, your server (or serverless functions) waits for the requests from the Cloud Services server instead.

To use the feature, you should enable [webhooks](#cs/latest/developer-resources/webhooks/overview.html) in the [Customer Portal](https://portal.ckeditor.com) or in the [Cloud Services Management Panel](#cs/latest/onpremises/cs-onpremises/management.html), provide a URL to your server and enable the [collaboration.document.exported](#cs/latest/developer-resources/webhooks/events.html--collaboration-session-exported) event. When the collaboration session ends, the request with the document content will be sent to the provided URL. Refer to the webhooks section in the documenation for more details. Also, check [other webhook events related to collaboration](#cs/latest/developer-resources/webhooks/events.html--collaboration) that can be useful when using webhooks to save document data.

The collaboration session ends 24 hours after the last user disconnects from it. If your application needs to access the document content before the collaboration session expires it is possible to manually remove the collaboration session using [a flush method](https://help.cke-cs.com/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument%5Fid%7D/delete) from Cloud Services REST API. This will also trigger a `collaboration.document.exported` webhook. You could also use the [collaboration.user.disconnected](#cs/latest/developer-resources/webhooks/events.html--user-disconnected) webhook event to check if there are no users connected and then trigger the flush to get the data in the `collaboration.document.exported` webhook. Please, keep in mind that this could impact the UX, when users refresh a page or have some network issues. It is recommended to use debounce or timeout mechanism that will cover brief disconnects from the collaboration sessions.

<a id="cs/latest/guides/collaboration/introduction.html--document-storage">

#### Document storage

Cloud Services also offer the [document storage](#cs/latest/guides/collaboration/document-storage.html) feature that allows you to permanently save the document data in CKEditor Cloud Services. In this case, the client-server handling used to store the document data is replaced with Cloud Services server. This is especially convenient for clients that value speed and security. When a user connects to a previously existing document for which a collaboration session has already expired, the document is automatically loaded into a new collaboration session.

<a id="cs/latest/guides/collaboration/introduction.html--benefits-of-the-document-storage-feature">

##### Benefits of the document storage feature

* Reduced number of requests to your server. Collaborating users no longer need to send the document data in time intervals.
* Your server is completely excluded from the responsibility of saving the document.
* The process of saving the document data is independent of the users’ or your server’s network conditions.
* No need to check whether a collaborative document session currently exists.
* No need to load the current content of the document in case the collaboration session has expired.
* No [race condition problem](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html--the-clouddocumentversion-property) when saving the document data.
* Documents are saved in an encrypted form.
* It is possible to get or delete documents from the storage or get the documents list via the REST API.

Check out the [document storage guide](#cs/latest/guides/collaboration/document-storage.html) for implementation details.

<a id="cs/latest/guides/collaboration/introduction.html--the-autosave-plugin">

#### The autosave plugin

While using the [autosave plugin](#ckeditor5/latest/features/autosave.html), user data is periodically sent to the client’s server, where it can be handled, validated and stored in the database. See the diagram below for the details of the process.

This method, although the simplest to implement, has its drawbacks:

* There is a race condition issue when many users are working on the same document and you need to ensure that you save the most recent version of the document.
* The data is coming from an untrusted source (the end-user) and may be manipulated.
* When opening previously edited documents, the user needs to fetch the content from the database to use it as the initial data.
* It increases the number of requests and the traffic to your server.
* It may be slow, especially when a large document is edited by a user with a poor internet connection.

<a id="cs/latest/guides/collaboration/introduction.html--ways-of-initializing-the-collaboration-session-with-data">

### Ways of initializing the collaboration session with data

The users will not always start from an empty editor and finish the document in one collaboration session. There is hence the need to initialize the editor with the previously saved versions of content or with some generated templates. Similar to getting the collaboration data, there are few ways to start a new collaboration session with your content:

* Use the [initialData](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcore%5Feditor%5Feditorconfig-EditorConfig.html#member-initialData) property in the editor configuration – the content passed to this property will be used when the user opens the editor. It will not overwrite the data if the collaboration session already exists.
* Use [document import](#cs/latest/guides/collaboration/document-import-and-export.html) from the Cloud Services REST API – your server can initialize the content in the collaboration session with all comments and suggestions with a single API call, and then the users will be able to connect to this collaboration session.
* Use [collaboration import](#cs/latest/guides/collaboration/import-and-export.html) from the Cloud Services REST API – your server can initialize the content in the collaboration session ( without comments and suggestions) with a single API call, and then the users will be able to connect to this collaboration session.
* Use [document storage](#cs/latest/guides/collaboration/document-storage.html) – if you enabled this feature, then opening previously edited documents will be automatically initialized with the saved content.

Refer to the [import and export](#cs/latest/guides/collaboration/import-and-export.html) and [document storage](#cs/latest/guides/collaboration/document-storage.html) guides for implementation details.

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html">source file: "cs/latest/guides/collaboration/migrating-to-rtc.html"</a>

## Migrating to Real-time Collaboration

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--overview">

### Overview

This article aims to explain the prerequisites and process of migrating Non Real-time Collaboration Features to the Real-time version. Thanks to this, your documents will be able to be edited simultaneously by many users. Your application will also be excluded from the responsibility of processing and synchronizing the data.

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--differences-between-real-time-and-non-real-time-collaboration">

#### Differences between Real-time and non Real-time Collaboration

In non Real-time Collaboration you have to implement adapters for each object that would process the data from the editor. A server application has to be implemented as well to store and synchronize the data:

In [Real-time Collaboration](#ckeditor5/latest/features/collaboration/collaboration.html) all the logic required for synchronising and saving the data is handled by the CKEditor5 Real-time Collaborative plugins and the CKEditor Cloud Services.

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--prerequisites">

### Prerequisites

In order to take full advantage of Real-time Collaboration Features you will need:

1. Active CKEditor Cloud Services [subscription](#cs/latest/guides/collaboration/quick-start.html--subscribe-to-the-collaboration-service).
2. A Real-time Collaboration editor build integrated with [CKEditor Cloud Services](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html).
3. A [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) prepared. It is required to authenticate users connected to the Real-time Collaborative Editing Sessions.

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--migrating-your-data-to-the-real-time-collaboration">

### Migrating your data to the Real-time Collaboration

The migration process can be summarized in these steps:

1. For each separate editor build you were using prepare a separate editor bundle with RTC features.
2. Get data for each [document](#cs/latest/guides/basic-concepts/data-model.html--document) and each [user](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html) you want to migrate to the Real-time Collaboration from your server
3. Map the data according to the CKEditor Cloud Services requirements and upload it using the [REST API](#cs/latest/developer-resources/apis/overview.html). Please note that all requests to the CKEditor Cloud Services REST API require [authentication](#cs/latest/developer-resources/apis/authentication.html).

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--uploading-editor-bundle">

#### Uploading editor bundle

To take full advantage of the Real-time Collaboration an [editor bundle](#cs/latest/guides/basic-concepts/editor-bundle.html) has to be uploaded to the server. For each editor build you were using in the asynchronous collaboration a respective bundle would have to be created.  
Since in Real-time Collaboration your server is excluded from the responsibility of synchronizing the data, the build does not have to include adapters for each resource (comments, track changes, etc.). To ensure data consistency, the bundled editor should include **every other plugin** that was used in the non-RTC editor.

You can learn more about preparing and uploading an editor bundle in our dedicated [guideline](#cs/latest/guides/collaboration/editor-bundle.html)

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--migrating-user-data">

#### Migrating user data

The real-time collaborative editing plugin will define user data and permissions automatically based on [your token data](#cs/latest/developer-resources/security/token-endpoint.html--user). If you want to migrate the user data manually your server would also have to store the user data and it would also have to be prepared at this step.  
For each user you want to migrate call the [REST API endpoint POST /users](https://help.cke-cs.com/api/v5/docs#tag/Users/paths/~1users/post)

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--migrating-document-data">

#### Migrating document data

To be able to collaborate in real-time on a given document its data would have to be migrated to the CKEditor Cloud Services. In order to do so, you need to get the data from your server application for each resource present on the document and map each field according to the requirements specified in the [REST API endpoint POST /documents](https://help.cke-cs.com/api/v5/docs#tag/Documents/paths/~1documents/post) and call it. After a successful response from the server, you can start collaborating on the document in Real-time and let the CKEditor Cloud Services handle the rest.

For Real-time Collaboration to work properly some fields not present in the non-RTC collaboration are required:

1. `suggestion.author_id` – Each suggestion in Real-time Collaboration should be linked with a user that requested it. In Real-time Collaboration this value is set automatically. If you don’t save information about who posted the suggestion on your server, you can either set some anonymous user as the suggestion author or create a user using Users REST API and then assign it as the author of every suggestion from the non-RTC collaboration.
2. `content.version` – Each document has its version set based on the operations performed. This value is required to import revisions to the Real-time Collaboration. If you want to migrate document with revisions you can set this value as the highest `toVersion` value from migrated revisions.
3. `comment.type` – This field is used by the CKEditor Cloud Services to determine whether a given comment is placed under the suggestion or another comment. The type for a regular comment is `1` and for the suggestion comments it’s `2`  
If you don’t store such information you can determine it by trying to find a matching suggestion by comparing its ID with the ID of a given comment thread. If for a given comment thread a matching suggestion would be found, you can set `type = 2` for each comment under that comment thread. Otherwise, it should be set to `1`. A simplified example can look as follows:

```
function getCommentThreadsData( commentThreadsForDocument, suggestionsForDocument ) {
    const threads = [];
    const comments = [];

    commentThreadsForDocument.forEach( commentThread => {
        const hasMatchingSuggestion = suggestionsForDocument.some( suggestion => suggestion.id === commentThread.id );

        threads.push( {
            // map your comment thread here
        } );

        comments.push(
            ...commentThread.comments.map( comment => ( {
                // map other comment fields here
                // set comment type depending if a comment thread it belongs to has a matching suggestion
               type: hasMatchingSuggestion ? 2 : 1
            } ) )
        );
    } );

    return {
        threads,
        comments
    }
}

```

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--example">

### Example

Check an [example of an application that migrates documents to Real-time Collaboration in Node.js and Express.js](#cs/latest/examples/collaboration-examples/migrating-document-to-rtc.html).

<a id="cs/latest/guides/collaboration/migrating-to-rtc.html--next-steps">

### Next steps

* Learn about how the [CKEditor Cloud Services stores and manages data](#cs/latest/guides/collaboration/data.html).
* Learn about [RTC features](#cs/latest/guides/collaboration/introduction.html).
* Learn about [system security and data safety](#cs/latest/guides/system-security.html).

<a id="cs/latest/guides/collaboration/quick-start.html">source file: "cs/latest/guides/collaboration/quick-start.html"</a>

## Quick start

The aim of this article is to get you up and running with [CKEditor 5 Collaboration Features](https://ckeditor.com/collaboration/).

Follow the steps below:

* Please [contact us](https://ckeditor.com/contact/) to purchase the Real-time collaboration features license.
* Generate your access credentials in the [Customer Portal](https://portal.ckeditor.com/).
* Write a script that generates one-time tokens for authorizing end users of your application in CKEditor Cloud Services (using access credentials created earlier).
* Create a [CKEditor 5 build with support for collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html) and configure it.

All steps are explained in detail below.

<a id="cs/latest/guides/collaboration/quick-start.html--subscribe-to-the-collaboration-service">

### Subscribe to the Collaboration service

Sign up for the [Collaboration service](https://portal.ckeditor.com/checkout?plan=free). After signing up, you will receive access to the customer dashboard (Customer Portal).

<a id="cs/latest/guides/collaboration/quick-start.html--log-in-to-the-customer-portal">

### Log in to the Customer Portal

Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Cloud environments”.

<a id="cs/latest/guides/collaboration/quick-start.html--create-token-endpoint">

### Create token endpoint

You now need to create a [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

<a id="cs/latest/guides/collaboration/quick-start.html--development-token-endpoint">

#### Development token endpoint

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in two simple steps:

1. From the list of environments select the one that you want to manage. To create a new environment, follow [instructions](#cs/latest/developer-resources/environments/environments-management.html).
1. The development token URL is accessible at the bottom of this section:

<a id="cs/latest/guides/collaboration/quick-start.html--simulating-random-users-and-roles">

##### Simulating random users and roles

The development token URL will generate random user data by default. As mentioned above, the user data will be returned from the pool of 10 predefined users. If you would like to specify your user details or set different roles and permissions, you may pass them in the query string using:

* `sub` (Optional) – The unique ID of the user in your system.
* `user.name` (Optional) – Full name.
* `user.email` (Optional) – Email address.
* `user.avatar` (Optional) – The URL to an avatar.
* `data` (Optional) – The custom data can be used to store any data.
* `role` (Optional) – User [role](#cs/latest/developer-resources/security/roles.html--roles) set in the token payload. The default role is `writer`.
* `additionalPermissions` (Optional) – Additional [permissions](#cs/latest/developer-resources/security/roles.html--permissions) that will be added in the token payload. When adding multiple permissions, separate them with `,` character.

So, if your token URL is `https://17717-dev.cke-cs.com/token/dev/XXX` then you may connect to CKEditor Cloud Services as the user _Jane Doe_ with the ID _13_ using the customized development token URL: `https://17717-dev.cke-cs.com/token/dev/XXX?user.name=Jane%20Doe&sub=13`

<a id="cs/latest/guides/collaboration/quick-start.html--extending-the-default-user-limit">

##### Extending the default user limit

There might be a need to extend the default limit of 10 development users. In order to do this, add a limit query parameter to your dev token URL.  
For example:

`https://17717-dev.cke-cs.com/token/dev/XXX?limit=40`

Using the above URL you will obtain a token for a user from a pool of 40 predefined users. Bear in mind that after the 10th token, you will start paying for development users. The maximum allowed value for the limit parameter is 50\. Therefore, the maximum number of paid users will be equal to 40 with the usage of our predefined users. Please remember that using your own generated user IDs may result in an unpredictable number of paid users.

<a id="cs/latest/guides/collaboration/quick-start.html--writing-your-own-token-endpoint">

#### Writing your own token endpoint

To write your own [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html), you need to create access credentials for the selected environment by going to the “Access credentials” tab and clicking the “Create a new access key” button.

Read more in the [Creating access credentials](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/collaboration/quick-start.html--cloud-region">

### Cloud region

Please note that Cloud Services can [reside in either US or EU region or in both](#cs/latest/guides/saas-vs-on-premises.html--cloud-region). The region is set per subscription and cannot be changed for existing environments by the user. For Custom plan with multi-region it is possible to choose the region during environment creation. This topic is addressed in more detail in the [Environment management](#cs/latest/developer-resources/environments/environments-management.html--cloud-region) guide.

<a id="cs/latest/guides/collaboration/quick-start.html--next-steps">

### Next steps

[Learn how to enable collaboration features in CKEditor 5](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration-integration.html).

<a id="cs/latest/guides/collaboration/server-side-editor-api.html">source file: "cs/latest/guides/collaboration/server-side-editor-api.html"</a>

## Server-side Editor API

The Server-side Editor API enables deep and complex integration of your application with all document data, enabling you to manipulate content and manage collaborative data such as suggestions, comments, and revision history, and much more, directly from your server-side code.

The remote script REST API endpoint allows you to execute any JavaScript code that uses the CKEditor 5 API, that could be executed by a browser, but without the need to open the editor by a human user. Instead, the script is executed on the Cloud Services server allowing for updating and interacting with active collaboration sessions remotely.

<a id="cs/latest/guides/collaboration/server-side-editor-api.html--why-use-server-side-editor-api">

### Why use server-side editor API?

There are many scenarios where server-side content processing is essential:

* **Automation**: Run content processing tasks as part of your backend workflows.
* **Scalability**: Process multiple documents simultaneously without client-side limitations.
* **Security**: Process sensitive content in a controlled environment without exposing it to client-side manipulation.
* **Performance**: Handle large-scale content operations without impacting the user’s browser.
* **Consistency**: Ensure uniform content changes across multiple documents.
* **Integration**: Connect with other server-side systems and databases directly.

<a id="cs/latest/guides/collaboration/server-side-editor-api.html--common-use-cases">

### Common use cases

* **Deep integration**: Build custom features that can manage document content and related document data straight from your application UI, without a need to open the editor.
* **Content migration**: Restructure and update references across multiple documents, perfect for website redesigns or content reorganization.
* **Shared content blocks**: Automatically update reusable content (like headers, footers, or common sections) across all documents that use it.
* **Automated review systems**: Build systems that automatically review and suggest content changes, like grammar checks or style improvements.
* **AI-powered editing**: Make automated suggestions while users are actively editing, helping improve content quality.
* **Automated publishing**: Prepare and process content for publication, including formatting, metadata updates, and resolving comments.

<a id="cs/latest/guides/collaboration/server-side-editor-api.html--quick-example">

### Quick example

Here’s a basic example of how to use the Server-side Editor API:

**Endpoint:**

```
POST /collaborations/{document_id}/evaluate-script

```

**Request body:**

```
{
    "script": "const content = editor.getData(); return { content: content, wordCount: content.split(' ').length };",
}

```

**Response:**

```
{
    "data": {
        "content": "<p>Document content here...</p>",
        "wordCount": 15
    }
}

```

<a id="cs/latest/guides/collaboration/server-side-editor-api.html--next-steps">

### Next steps

* [Server-side Editor API reference](#cs/latest/developer-resources/server-side-editor-api/editor-scripts.html): learn more details about the requests and response structure of editor scripts for server-side content manipulation.

<a id="cs/latest/guides/export-to-pdf/overview.html">source file: "cs/latest/guides/export-to-pdf/overview.html"</a>

## Export to PDF - overview

CKEditor Cloud Services offer a fast and highly scalable service enabling the user to export documents to PDF document. The feature is available as a service, making it possible to send an HTML string straight into the Cloud Services server for more advanced use or as convenient WYSIWYG editor plugins for the ease of use in less demanding cases.

<a id="cs/latest/guides/export-to-pdf/overview.html--pagination-feature">

### Pagination feature

The complementary premium [pagination feature for CKEditor 5](#ckeditor5/latest/features/pagination/pagination.html) allows you to see where page breaks would be after the document is exported to PDF. Thanks to the live preview, the user is able to fine-tune the structure of the output document when editing it. In addition to this, the pagination feature shows you the page count and allows to easily navigate between the document pages.

<a id="cs/latest/guides/export-to-pdf/overview.html--integration-with-merge-fields-content-placeholders">

### Integration with merge fields (content placeholders)

[Merge fields](#ckeditor5/latest/features/merge-fields.html) are visually distinct placeholder elements you can put into the content to mark places where real values should be inserted. It is perfect for creating document templates and other kinds of personalized, serialized content. This allows for automation and creating batch output of personalized PDF files. Learn how to configure it in the [configuration section of the merge fields guide](#ckeditor5/latest/features/merge-fields.html--using-callbacks-to-define-values).

<a id="cs/latest/guides/export-to-pdf/overview.html--how-the-export-to-pdf-feature-works">

### How the Export to PDF feature works

The HTML to PDF converter provides an API for converting HTML documents to PDF files. The service generates a file and returns it to the user so they can save it in the `.pdf` format on their disk. To integrate the feature into your environment, first check the [Quick start](#cs/latest/guides/export-to-pdf/quick-start.html) guide to start using it.

You can also test the feature using [the export to PDF demo page](https://pdf-converter.cke-cs.com/v2/convert/demo).

<a id="cs/latest/guides/export-to-pdf/overview.html--the-html-to-pdf-converter-request">

### The HTML to PDF converter request

The following properties are available while using the converter service:

* [html](#cs/latest/guides/export-to-pdf/overview.html--html)
* [css](#cs/latest/guides/export-to-pdf/overview.html--css)
* [config](#cs/latest/guides/export-to-pdf/overview.html--configuration)

If you want to use this API directly, you need to provide proper CSS code manually. To achieve this, you should pass a string that is a concatenation of the default editor styles (refer to the [CKEditor 5’s content styling](#ckeditor5/latest/getting-started/setup/css.html--styling-the-published-content) guide) and, optionally, your custom styles to the `css` property. With the default editor configuration, you do not need to specify the `config` property.

<a id="cs/latest/guides/export-to-pdf/overview.html--html">

#### HTML

Any `HTML` compliant content can be sent to the converter.

* All HTML documents use the `<!DOCTYPE html>` declaration to generate PDF files.
* The recommended way to generate a PDF document is to send only the HTML content. However, if your document requires a full HTML structure to render properly, you can use it.

<a id="cs/latest/guides/export-to-pdf/overview.html--css">

#### CSS

This option is used to send custom CSS styles.

<a id="cs/latest/guides/export-to-pdf/overview.html--configuration">

#### Configuration

The `config` section defines the details of your PDF conversion request.

Options such as margins, page size, and orientation are available to control the visual arrangement of the document. The implementation of mirror margins facilitates book-like layouts.

You can define headers and footers for the output PDF. The converter supports distinct header and footer variations (first page, odd pages, even pages, and default) to allow for differentiated content across pages.

Beyond content and layout, the configuration allows for control over other PDF attributes. You can set PDF metadata to enhance document discoverability for search and cataloging purposes. Password protection can be applied to restrict file access. You can also include digital signatures to confirm the origin and integrity of the PDF.

Refer to the [converter documentation](https://pdf-converter.cke-cs.com/v2/convert/docs#section/Export-to-PDF-%28v2%29/Configuration) for details on the syntax and usage of all the available options.

<a id="cs/latest/guides/export-to-pdf/overview.html--images">

#### Images

Images can be either inserted from a URL or Base64-encoded, using the `src` attribute of the `<img>` tag.

<a id="cs/latest/guides/export-to-pdf/overview.html--web-fonts">

#### Web Fonts

To generate PDF documents, you can use web fonts like in a regular browser. You need to specify the URL to the font file or a font file converted to the Base64 format.

Refer to the [converter documentation](https://pdf-converter.cke-cs.com/v2/convert/docs#section/Web-Fonts) for details and examples.

<a id="cs/latest/guides/export-to-pdf/overview.html--the-export-to-pdf-editor-plugin">

### The Export to PDF editor plugin

The [Export to PDF CKEditor plugin](#ckeditor5/latest/features/converters/export-pdf.html) allows you to easily print the WYSIWYG editor content to a PDF file. When enabled, this feature sends the content of your editor together with the styles that are used to display it to the CKEditor Cloud Services HTML to PDF converter service. The service then generates a PDF document that the user can download.

Thanks to this plugin, it takes exactly one button click to get a PDF file with content formatted the same way as displayed in the CKEditor WYSIWYG editor. An easy solution for integrations, that does not demand editor data to be processed further once it is edited.

<a id="cs/latest/guides/export-to-pdf/overview.html--stored-data">

### Stored data

Export to PDF is a service that generates PDF files based on the data provided by the customer (HTML, CSS). To perform the conversion, it requires the data sent from the editor or a database, but the service itself is fully stateless.

The data (especially your sensitive data: HTML, CSS, comments) is used only during the processing. However, we store some information needed for billing and maintaining our system. We try to reduce stored data to a required minimum and at this moment we store such information as the number and duration of exports, the final document size, the number of unique exports, statistical data (used features, IP addresses, editor versions).

All logs related to processing requests are saved only in case of unexpected situations and are stored for 90 days. The data in logs includes an error message, stack trace, and information about the request.

<a id="cs/latest/guides/export-to-pdf/quick-start.html">source file: "cs/latest/guides/export-to-pdf/quick-start.html"</a>

## Export to PDF - quick start

The aim of this article is to get you up and running with the Export to PDF service.

Follow these steps:

* Subscribe to Export to PDF on the [Premium Features Free Trial website](https://portal.ckeditor.com/checkout?plan=free).
* Generate your access credentials in the [Customer Portal](https://portal.ckeditor.com/).
* Configure CKEditor.

All the steps are explained in details below.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--subscribe-to-ckeditor-cloud-services">

### Subscribe to CKEditor Cloud Services

Create an account in CKEditor Cloud Services by signing up to Export to PDF. After signing up, you will receive access to the customer dashboard (Customer Portal).

<a id="cs/latest/guides/export-to-pdf/quick-start.html--log-in-to-the-customer-portal">

### Log in to the Customer Portal

Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Your products > Cloud Services”.

From the list of available subscriptions in the dashboard choose the Export to PDF subscription that you want to manage and press the “Manage” link.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--using-the-service-with-rest-api">

### Using the service with REST API

The Export to PDF service may be used to convert an HTML string into a PDF file. In order to use it, authorization is needed in the form of an authorization token.

The authorization token need to be passed as a value of the `Authorization` header.

```
{
    'Authorization': 'Your generated authorization token'
}

```

<a id="cs/latest/guides/export-to-pdf/quick-start.html--generating-the-authorization-token">

#### Generating the authorization token

The authorization token can be generated in two ways:

1. As a value returned from the [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) URL.
2. Locally created token.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--creating-access-credentials">

#### Creating access credentials

From the list of environments select the one that you want to manage.

Go to the “Access credentials” tab and click the “Create a new access key” button.

The modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

For your safety, the access key value will disappear in a few seconds. You will be able to display it again by clicking the “Show” button. Make sure to keep the access credentials in a safe place.

Read more about dealing with the credentials in the [Managing access credentials](#cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--example-request">

#### Example request

Tokens for the HTML to PDF converter service require passing a payload with the `aud` parameter and a valid `iat`:

* `aud` – The environment ID.
* `iat` – Issued at.

The `accessKey` value needs to be replaced with your own access key generated before.

The following example presents a request that contains the required `Authorization` header for the HTML to PDF converter:

```
const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const accessKey = 'iGC6md5EcTG0DDZqEf4m4eytr679z0Ch2gIQuraBPzyWEtTbcpQAqAhA9LxpkDtpn';
const environmentId = 'DO3zekDU3LiJX8GOL2xt';

const token = jwt.sign( { aud: environmentId, iat: Math.floor( Date.now() / 1000 ) }, accessKey, { algorithm: 'HS256' } );

const data = {
   html: '<p>I am a teapot</p>',
   css: 'p { color: red; }',
   config: {
      document: {
         margins: {
            top: '2cm'
         }
      }
   }
};

const config = {
   headers: {
      'Authorization': token
   },
   responseType: 'arraybuffer',
};

axios.post( 'https://pdf-converter.cke-cs.com/v2/convert/html-pdf', data, config )
   .then( response => {
      fs.writeFileSync('./file.pdf', response.data, 'binary')
   } ).catch( error => {
      console.log( error );
   } );

```

Please refer to the [converter documentation](https://pdf-converter.cke-cs.com/v2/convert/docs) to start using the REST API service.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--using-the-export-to-pdf-feature-as-a-plugin">

### Using the Export to PDF feature as a plugin

In order to use the export to PDF feature in your CKEditor 5 build, a token URL is needed for authorization.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--creating-token-endpoint">

#### Creating token endpoint

Before you can use the feature, you first need to create a [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--development-token-endpoint-development-only">

##### Development token endpoint (development only)

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in three simple steps:

1. To work with CKEditor premium features like real-time collaboration, exports and import you need to create an environment. Environments allow you to create access credentials, manage webhooks, configure features and connect to CKEditor Cloud Services. You may have more than one to serve separate instances or integrations. From the list the environments choose the one that you want to manage.
1. The development token URL will show up in the “Development token URL” section:

<a id="cs/latest/guides/export-to-pdf/quick-start.html--writing-your-own-token-endpoint-production">

##### Writing your own token endpoint (production)

To write your own [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html), you need to create access credentials for the selected environment by going to the “Access credentials” tab and clicking the “Create a new access key” button.

Read more in the [Creating access credentials](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--integrating-the-export-to-pdf-plugin-with-the-application">

#### Integrating the Export to PDF plugin with the application

<a id="cs/latest/guides/export-to-pdf/quick-start.html--enabling-the-plugin-in-ckeditor-5">

##### Enabling the plugin in CKEditor 5

To install the plugin into your WYSIWYG editor, use the [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate a custom CKEditor 5 build with the plugin enabled. Alternatively, refer to the [installation guide](#ckeditor5/latest/features/converters/export-pdf.html--installation) in the plugin documentation to do it on your own.

Configure the plugin using the token generated earlier, pasting the link in the configuration (see [CloudServicesConfig](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html)):

```
    ClassicEditor
        .create( document.querySelector( '#editor' ), {
            exportPdf: {
                tokenUrl: 'https://example.com/cs-token-endpoint',
            }
        } )
        .then( ... )
        .catch( ... );

```

This is all. At this point, the export will be automatically enabled in your application.

Refer to the [CKEditor 5 guide](#ckeditor5/latest/features/converters/export-pdf.html--installation) for further details on adding the Export to PDF feature to your WYSIWYG editor!

<a id="cs/latest/guides/export-to-pdf/quick-start.html--enabling-the-plugin-in-ckeditor-4">

##### Enabling the plugin in CKEditor 4

You can use the [Online builder for CKEditor 4](https://ckeditor.com/cke4/builder) to integrate the Export to PDF plugin into your build.

There is just one thing you have to do to activate plugin - set a `exportPdf_tokenUrl` configuration option:

```
CKEDITOR.replace( 'editor', {
    exportPdf_tokenUrl: 'https://example.com/cs-token-endpoint'
} )

```

Refer to the [Export to PDF configuration guide](https://ckeditor.com/docs/ckeditor4/latest/features/exporttopdf.html#configuration) for step-by-step integration walk-through.

<a id="cs/latest/guides/export-to-pdf/quick-start.html--using-additional-http-headers">

#### Using additional HTTP headers

If fetching some resources (for example, images) used in a generated PDF requires passing an additional authorization factor in the form of additional HTTP headers, you can define it in PDF `config.extra_http_headers`:

```
const data = {
   html: '<p>I am a teapot</p><img src="https://secured-example-website.com/image.jpg">',
   css: 'p { color: red; }',
   config: {
      extra_http_headers: {
         'https://secured-example-website.com': {
            authorization: 'Bearer RDp0NqyePooNWFIWvHtbKrKKHLXfmLfZcv3PRpCyJI90uwi3pKvumKl2vymCxoGFw6Vx'
         }
      }
   }
};

axios.post( 'https://pdf-converter.cke-cs.com/v2/convert/html-pdf', data, config )
   .then( response => {
      fs.writeFileSync('./file.pdf', response.data, 'binary')
   } ).catch( error => {
      console.log( error );
   } );

```

<a id="cs/latest/guides/export-to-word/collaboration-features.html">source file: "cs/latest/guides/export-to-word/collaboration-features.html"</a>

## Supported collaboration features

The Export to Word converter supports Word’s collaboration features, namely the comments and track changes. The comments feature lets you add a notice about a selected part of the content, whereas track changes allow for proposing a change inside the content, like deletion, insertion, or replacement of a selected part of the content.

Both features are also implemented by CKEditor 5, so make sure to read [CKEditor 5 comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [CKEditor 5 track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) guides to learn more.

Note that despite that Export to Word requires HTML in a format compatible with CKEditor 5 collaboration features, the converter alone is technology-agnostic. It can be used with custom integrations on your end – as long as it supports the same content format.

<a id="cs/latest/guides/export-to-word/collaboration-features.html--comments">

### Comments

Comments are an advanced feature of Word that is supported by the Export to Word feature with full compatibility with [CKEditor 5 comments](#ckeditor5/latest/features/collaboration/comments/comments.html). Comments allow users to add notes to the document without changing the content itself.

Comments data is supplied to the converter via the `config.collaboration_features.comment_threads` configuration option. Comments metadata consists of an array of comment threads, which contain the following properties:

* `thread_id`: A string ID of the thread (**required**).
* `is_resolved`: A boolean that determines whether the thread is resolved (**defaults to false**).
* `comments`: An array of comments belonging to the thread. They contain the following properties:  
  * `content`: HTML content of the comment (**required**).
  * `author`: A comment author’s name (**required**).
  * `created_at`: Date and time describing when the comment was created in ISO 8601 format (**optional**).

An example of converting HTML content with comments to a Word document:

```
<p>
    <comment-start name="comment-thread-1"></comment-start>
    Hello world!
    <comment-end name="comment-thread-1"></comment-end>
</p>

```

```
{
    "config": {
        "collaboration_features": {
            "comment_threads": [
                {
                    "thread_Id": "comment-thread-1",
                    "resolved": false,
                    "comments": [
                        {
                            {
                                "author": "User 1",
                                "content": "<p>This is an example comment.</p>",
                                "created_at": "2024-05-12T10:00:00.000Z",
                            },
                            {
                                "author": "User 2",
                                "content": "<p>This is another example comment.</p>",
                                "created_at": "2024-05-12T10:30:00.000Z",
                            },
                        }
                    ]
                }
            ]
        }
    }
}

```

Export to Word converter supports converting [paragraphs](#cs/latest/guides/export-to-word/content-formatting.html--paragraphs), [inline HTML elements](#cs/latest/guides/export-to-word/content-formatting.html) and [hyperlinks](#cs/latest/guides/export-to-word/content-formatting.html--hyperlinks) as content of comments.

<a id="cs/latest/guides/export-to-word/collaboration-features.html--track-changes">

### Track changes

Track changes is another advanced feature that is also compatible with the [CKEditor 5 track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html). To start tracking changes in Word, select the Review tab from the ribbon and then enable the Track Changes option. Now any changes applied to the document will be tracked.

Track changes data is supplied to the converter via the `config.collaboration_features.suggestions`. Track changes metadata consist of an array of suggestions with the following properties:

* `id`: A string ID of the suggestion (**required**).
* `author`: A suggestion author’s name (**required**).
* `created_at`: Date and time describing when the suggestion was created in ISO 8601 format (**optional**).

Example of converting HTML content with suggestions to Word document:

```
<p>
    <suggestion-start name="insertion:0:user1"></suggestion-start>
    Insertion
    <suggestion-end name="insertion:0:user1"></suggestion-end>
</p>

<p>
    <suggestion-start name="deletion:1:user1"></suggestion-start>
    Deletion
    <suggestion-end name="deletion:1:user1"></suggestion-end>
</p>

```

```
{
    "config": {
        "collaboration_features": {
            "suggestions": [
                {
                    "id": "0",
                    "author": "User 1",
                    "created_at": "2024-05-12T10:00:00.000Z",
                },
                {
                    "id": "1",
                    "author": "User 1",
                    "created_at": "2024-05-12T10:30:00.000Z",
                }
            ]
        }
    }
}

```

<a id="cs/latest/guides/export-to-word/collaboration-features.html--timezone">

#### Timezone

The word track changes feature does not support dates with a specified time zone and all suggestions are treated as local dates and times. You can use the `config.timezone` option to offset such dates to a specified time zone.

Consider the conversion of the following document:

```
{
  "html": "<suggestion-start name=\"insertion:s1:user1\"></suggestion-start>Suggestion<suggestion-end name=\"insertion:s1:user1\"></suggestion-end>",
  "config": {
    "collaboration_features": {
      "suggestions": [
        {
          "id": "s1",
          "author": "User 1",
          "created_at": "2020-05-05T14:30:00.000Z"
        }
      ]
    }
  }
}

```

After opening the generated document in Word, it displays that the suggestion was created on May 5, 2020, at 2:30:00 PM, regardless of the local time zone.

With the time zone set to `America/Los_Angeles`, the previous suggestion would be displayed in Word as created on May 5, 2020, at 7:30:00 AM, regardless of the local time zone.

The provided time zone must be a valid [IANA time zone](https://www.iana.org/time-zones) identifier.

<a id="cs/latest/guides/export-to-word/content-formatting.html">source file: "cs/latest/guides/export-to-word/content-formatting.html"</a>

## Supported content formatting features

Export to Word is capable of converting HTML content to a Word document while preserving the original formatting of the content. The converter supports a wide range of HTML elements and CSS properties, allowing for the conversion of complex content structures.

This document provides an overview of the supported content formatting features, including text styles, inline elements, block elements, and common types of CSS properties.

You can style HTML content using inline styles, styles defined inside the `<style>` element, or styles provided via the [css configuration option](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/CSS). The converter supports style inheritance, so any properties set on ancestor elements also work in descendant elements, as long as the given property is inherited in CSS.

<a id="cs/latest/guides/export-to-word/content-formatting.html--text">

### Text

The converter supports many inline HTML elements that have default styling:

| Element name | Default style                               |
| ------------ | ------------------------------------------- |
| abbr         | –                                           |
| b            | font-weight: bold                           |
| br           | –                                           |
| cite         | font-style: italic                          |
| code         | font-family: monospace                      |
| del          | text-decoration: line-through solid black   |
| dfn          | font-style: italic;                         |
| em           | font-style: italic;                         |
| i            | font-style: italic;                         |
| ins          | text-decoration: underline solid black      |
| kbd          | font-family: monospace                      |
| mark         | background-color: yellow                    |
| s            | text-decoration: line-through solid black   |
| samp         | font-family: monospace                      |
| small        | font-size: smaller                          |
| span         | –                                           |
| strong       | font-weight: bold                           |
| sub          | vertical-alignment: sub; font-size: smaller |
| sup          | vertical-alignment: sup; font-size: smaller |
| u            | text-decoration: underline solid black      |
| var          | font-style: italic                          |

Additionally, all elements support the `id`, `class`, and `style` attributes, which can be used to format document content with various CSS properties. The following sections provide an overview of the supported CSS properties.

<a id="cs/latest/guides/export-to-word/content-formatting.html--font-size">

#### Font size

The size of a font can be controlled via the `font-size` property.

<a id="cs/latest/guides/export-to-word/content-formatting.html--font-family">

#### Font family

A font family can be set via the `font-family` property. When multiple font family names are specified, only the first one is used. For example, the following HTML will result in a document with `Courier New` font:

```
<span style="font-family: 'Courier New', Courier, monospace">
    Example text
</span>

```

Generic CSS font families are converted to well-known fonts as follows:

| Generic CSS font family | Word counterpart |
| ----------------------- | ---------------- |
| serif                   | Times New Roman  |
| sans-serif              | Arial            |
| cursive                 | Times New Roman  |
| fantasy                 | Impact           |
| monospace               | Courier New      |
| system-ui               | Verdana          |
| math                    | Times New Roman  |
| fangsong                | Times New Roman  |
| kai                     | Times New Roman  |
| nastaliq                | Times New Roman  |
| ui-serif                | Times New Roman  |
| ui-sans-serif           | Arial            |
| ui-monospace            | Courier New      |
| ui-rounded              | Times New Roman  |

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations">

##### Known limitations

* Not all fonts used in a document may be available in Word.

<a id="cs/latest/guides/export-to-word/content-formatting.html--font-style">

#### Font style

The style of a font can be set via the `font-style` property:

* `normal`: a font that is neither italic nor oblique
* `italic`: an italic font
* `oblique`: treated the same as `italic`

Custom slant angles in oblique fonts are not supported.

<a id="cs/latest/guides/export-to-word/content-formatting.html--font-weight">

#### Font weight

To make text bold, the `font-weight` property can be used. The following values result in bold text:

* `bold`
* Values greater than or equal to `700`

Other values are not supported.

<a id="cs/latest/guides/export-to-word/content-formatting.html--foreground-and-background-colors">

#### Foreground and background colors

The foreground and background colors can be specified via the `color` and `background-color` properties respectively. The converter supports only colors in the sRGB color space:

* Named colors such as `red`, `green`, or `blue`.
* A hexadecimal color notation such as `#FF000`, `#00FF00`, or `#0000FF`.
* sRGB color functions: `hsl()`, `hwb()`, or `rgb()`.

Other color spaces (such as CIELAB or Oklab) and custom color spaces are not supported.

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations-2">

##### Known limitations

* Support for semi-transparent background colors is limited. Overlapping semi-transparent colors are not mixed together.

<a id="cs/latest/guides/export-to-word/content-formatting.html--text-decoration">

#### Text decoration

Conversion of text decoration is supported to different extents based on the value of the `text-decoration-line` property. Only `underline` and `line-through` line types are supported.

<a id="cs/latest/guides/export-to-word/content-formatting.html--underline">

##### Underline

When the `text-decoration-line` property is set to `underline`, the converter underlines the text. The following other properties are supported for underlines:

* `text-decoration-style`: supports `solid`, `double`, `dotted`, `dashed`, and `wavy` values.
* `text-decoration-color`: supports the same values as [foreground and background colors](#cs/latest/guides/export-to-word/content-formatting.html--foreground-and-background-colors).

<a id="cs/latest/guides/export-to-word/content-formatting.html--strike-through">

##### Strike-through

When the `text-decoration-line` property is set to `line-through`, the converter generates strike-through text.

* `text-decoration-style`: supports `solid` and `double` values.

<a id="cs/latest/guides/export-to-word/content-formatting.html--subscript-and-superscript">

#### Subscript and superscript

To make text appear as subscript or superscript, the `vertical-align` property can be set to `sub` or `super` respectively.

<a id="cs/latest/guides/export-to-word/content-formatting.html--hyperlinks">

### Hyperlinks

Converter transforms `<a>` elements with the `href` attribute into hyperlinks.

Allowed URL schemes for the `href` attribute:

* `http`
* `https`
* `file`
* `ftp`
* `mailto`
* `sms`
* `tel`

You can change the base URL of hyperlinks using the `base_url` configuration option. The option changes all relative links to absolute ones. Read more about this option in the [API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Configuration).

`<a>` elements with hrefs: `#` and `#top` will be converted to links to the top of the document in Word. If document contains `<a>` element with `id` equal to `#top` then all `<a>` elements with href `#top` will point to that element instead.

<a id="cs/latest/guides/export-to-word/content-formatting.html--bookmarks">

### Bookmarks

Converter transforms `<a>` elements with the `id` attribute into bookmarks. This allows preserving behavior of linking HTML text fragments.

Maximum length for `id` attribute is 40 unicode characters as this is maximum length of bookmark name allowed in Word, any `id` longer than this will be trimmed down.

<a id="cs/latest/guides/export-to-word/content-formatting.html--images">

### Images

Converter supports conversion of `<img>` elements. The following attributes are supported:

* `src`
* `width`
* `height`
* `alt`

Empty `alt` attributes (`alt=""`) are treated interchangeably with missing `alt` attributes.

Allowed URL schemes for the `src` attribute:

* `http`
* `https`
* `data`

You can change the base URL of images using the `base_url` configuration option. The option changes all relative image sources to absolute ones. Read more about this option in the [API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Configuration).

Supported image formats include:

* `apng`
* `avif`
* `bmp`
* `gif`
* `heic`\*
* `jpg`
* `png`
* `svg`
* `tiff`\*
* `webp`

\* Conversion of the image width and height might not work properly.

The converter downloads and embeds all images into the document itself. This means that all images have to be accessible via the Internet at the time of conversion. When an image is not accessible, the converter generates an image that links to its source instead. However, Word displays such images only when a user is online and the images are accessible.

Word replaces missing images with a placeholder image. The size of that placeholder is not set unless the source image has the `width` and `height` attributes explicitly defined.

<a id="cs/latest/guides/export-to-word/content-formatting.html--image-captions">

#### Image captions

You can create an image caption with the `<figcaption>` element. For this feature to work properly, both `<figcaption>` and `<img>` must be placed inside a `<figure>` element.

Example of converting an image with a caption:

```
<figure>
    <img src="https://placeholder.com/200"/>
    <figcaption>This is caption of example image.</figcaption>
</figure>

```

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations-3">

##### Known limitations

* For a captioned image to be converted properly, there must be no other than the required elements inside the `<figure>` element.
* The caption is always positioned below the image.

<a id="cs/latest/guides/export-to-word/content-formatting.html--image-positioning">

#### Image positioning

Images inside a `<figure>` element can be additionally positioned. The following table is a breakdown of positioning types along with styles that must be applied to the `<figure>` element so that the converter properly generates positioned images.

| Positioning                                 | Styles applied to <figure> element    |
| ------------------------------------------- | ------------------------------------- |
| Image horizontally aligned to the left      | margin-left: 0; margin-right: auto    |
| Image horizontally centered                 | margin-left: auto; margin-right: auto |
| Image horizontally aligned to the right     | margin-left: auto; margin-right: 0    |
| Image with text wrapped from the left side  | float: right                          |
| Image with text wrapped from the right side | float: left                           |

<a id="cs/latest/guides/export-to-word/content-formatting.html--image-margins">

#### Image margins

The converter supports image margins, including margins for floating images with or without captions, but does not support margins for inline or block images. Margins can be applied to both the `<figure>` and the `<img>` elements, and their values will be combined and added to the image positioning.

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations-4">

##### Known limitations

* While margins in all directions are supported, those on the same side as the image alignment are ignored (for example, left margins for left-floating images and right margins for right-floating images). This limitation applies to floating images both with and without captions.

<a id="cs/latest/guides/export-to-word/content-formatting.html--paragraphs">

### Paragraphs

The converter converts `<p>` elements into paragraphs. Additionally, inline content placed outside any block element is automatically wrapped in a paragraph. Multiple subsequent inline elements outside a block element are wrapped in the same paragraph.

```
This is text content outside of any block element.<br />
<strong>That can be additionally styled.</strong>
<p>This is a paragraph</p>

```

Additionally, paragraphs support formatting properties described in the following sections.

<a id="cs/latest/guides/export-to-word/content-formatting.html--text-alignment">

#### Text alignment

Inline content can be aligned inside a paragraph via the `text-align` property. The following values are supported:

* `left`
* `center`
* `right`
* `justify`

<a id="cs/latest/guides/export-to-word/content-formatting.html--line-height">

#### Line height

The height of a line can be changed via the `line-height` property. The converter supports both unitless values and values with a unit specified. The `normal` value is treated the same as `1.2`.

<a id="cs/latest/guides/export-to-word/content-formatting.html--spacing-and-indentation">

#### Spacing and indentation

Spacing and indentation can be changed by applying the `margin` property:

* Indentation is controlled by `margin-left` and `margin-right` properties.
* Spacing above and below a paragraph is controlled by `margin-top` and `margin-bottom` properties respectively.

For example, consider the following HTML that sets the default paragraph spacing to 1 cm, and the left indentation of the middle paragraph to 4 cm:

```
<style>
p {
    margin-top: 1cm;
    margin-bottom: 1cm;
}
</style>

<p>First paragraph with the default indentation and 1cm spacing.</p>
<p style="margin-left: 4cm">Second paragraph with 4cm left indentation.</p>
<p>Third paragraph with the default indentation and 1cm spacing.</p>

```

<a id="cs/latest/guides/export-to-word/content-formatting.html--background-color">

#### Background color

It is possible to set the background color of a paragraph via the `background-color` property in the same way as the [background color of text](#cs/latest/guides/export-to-word/content-formatting.html--foreground-and-background-colors).

<a id="cs/latest/guides/export-to-word/content-formatting.html--headings">

### Headings

The converter supports all levels of HTML headings `<h1>` to `<h6>`. The headings are converted to corresponding Word Styles according to their level. See the [Word Styles](#cs/latest/guides/export-to-word/styles.html--word-styles) section for more information.

Headings support the same content formatting as paragraphs.

<a id="cs/latest/guides/export-to-word/content-formatting.html--lists">

### Lists

The converter supports both ordered `<ol>` and unordered `<ul>` lists.

Nested lists are supported up to 9 levels of nesting, levels greater than 9 are coerced to 9, which is the maximum level that Word supports.

The starting value of ordered lists can be changed using the `start` attribute. Negative values are coerced to 0 as Word does not support them.

Example:

```
<ul>
    <li>First item</li>
    <li>
        Second item
        <ul>
            <li>Third item</li>
        </ul>
    </li>
</ul>
<ol start="4">
    <li>Fourth item</li>
    <li>Fifth item</li>
</ol>

```

<a id="cs/latest/guides/export-to-word/content-formatting.html--marker-type">

#### Marker type

The style of list item markers can be changed by applying the `list-style-type` property to `<ol>` and `<ul>` elements.

Only the following types are supported:

* `decimal`
* `decimal-leading-zero`
* `lower-alpha`
* `lower-latin`
* `upper-alpha`
* `upper-latin`
* `lower-roman`
* `upper-roman`
* `disc`
* `circle`
* `square`
* `none`

Unsupported list types are treated as `disc`.

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations-5">

#### Known limitations

* [Multi-level lists](https://ckeditor.com/docs/trial/latest/guides/standalone/multi-level-lists.html) are not supported yet.
* Formatting of list item markers is not supported. Similarly, `list-style-type` cannot be applied to `<li>` elements.
* Indentation of lists and their content is not supported.
* Reversed lists are not supported due to Word limitations.

<a id="cs/latest/guides/export-to-word/content-formatting.html--tables">

### Tables

The converter converts any `<table>` element to a table. The `<table>` element can be placed in a `<figure>` element, inside table cells (allowing for nested tables), or just placed inside the document body.

```
<style>
    table {
        border-collapse: collapse;
    }
    th,
    td {
        border: 1px solid black;
        padding: 10px;
    }
</style>
<figure>
    <table>
        <thead>
            <tr>
                <th>Cell 1</th>
                <th>Cell 2</th>
                <th>Cell 3</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Cell 1</td>
                <td>Cell 2</td>
                <td>Cell 3</td>
            </tr>
            <tr>
                <td>Cell 4</td>
                <td>Cell 5</td>
                <td>Cell 6</td>
            </tr>
        </tbody>
    </table>
</figure>

```

Additionally, the converter supports the following obsolete table attributes:

* `align`
* `bgcolor`
* `border`
* `cellpadding`
* `cellspacing`
* `frame`
* `rules`
* `width`

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-columns">

#### Table columns

Columns of a table can be defined with `<colgroup>` and `<col>` elements. Both are supported by the converter. The converter supports the `span` attribute on these elements, too.

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-rows">

#### Table rows

The converter supports `<thead>`, `<tbody>`, and `<tfoot>` row group elements as well as the `<tr>` element. Only the first `<thead>` and `<tfoot>` elements are recognized as the table header and footer, and if they’re placed in wrong order, the converter moves them so that they’re placed at the table start or end respectively.

Any rows inside the first `<thead>` element are treated as header rows and repeat on every new page in Word.

The following obsolete attributes are supported in these elements:

* `bgcolor`
* `valign`

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-cells">

#### Table cells

Table cells are defined with `<th>` and `<td>` elements. Since Word does not support header cells, the `<th>` element is treated interchangeably with the `<td>` element.

Table cells may span multiple columns or rows by applying the `colspan` or `rowspan` attributes to them. However, `rowspan` cannot exceed the number of rows in the current row group, otherwise it’s coerced to that number instead.

Table cells support the following obsolete attributes:

* `bgcolor`
* `height`
* `valign`
* `width`

Additionally, the `scope` attribute may be applied to `<th>` elements, although the converter ignores it.

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-positioning">

#### Table positioning

Tables can be positioned similarly to images, but the required styles may be applied either to the `<table>` element itself or the parent `<figure>` element. Left and right margins can be used to align a table horizontally.

| Positioning                             | Styles applied to <table> or <figure> element |
| --------------------------------------- | --------------------------------------------- |
| Table horizontally aligned to the left  | margin-left: 0; margin-right: auto            |
| Table horizontally centered             | margin-left: auto; margin-right: auto         |
| Table horizontally aligned to the right | margin-left: auto; margin-right: 0            |

The `float` property can align a table to the left or right side with text wrapping on the opposite side.

| Positioning                                 | Styles applied to <table> or <figure> element |
| ------------------------------------------- | --------------------------------------------- |
| Table with text wrapped from the left side  | float: right                                  |
| Table with text wrapped from the right side | float: left                                   |

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-borders">

#### Table borders

All table elements can be used to style table borders with the following properties:

* `border-color`
* `border-style`
* `border-width`

The `ridge` and `groove` line styles are converted to `inset` and `outset` respectively, which Word renders differently from browsers. Additionally, `double` borders are transformed into `solid` ones if their width is less than or equal to 1 px.

Border colors support the same values as the [foreground and background colors of text](#cs/latest/guides/export-to-word/content-formatting.html--foreground-and-background-colors). The minimum and maximum border width supported by Word is 0.333… px and 16 px respectively. Values outside this range are coerced to boundary values.

Moreover, the `<table>` element supports two extra border-related properties:

* `border-collapse`
* `border-spacing`

They can be used to control whether the borders of a table should be collapsed or separated. Word does not support separate borders without spacing, so in such cases, the converter sets the spacing to the minimum value of 0.05 pt.

<a id="cs/latest/guides/export-to-word/content-formatting.html--background-color-2">

#### Background color

The background color of any table element can be set via the `background-color` property similarly to the [background color of text](#cs/latest/guides/export-to-word/content-formatting.html--foreground-and-background-colors).

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-and-table-cell-width">

#### Table and table cell width

The `<table>`, `<th>`, and `<td>` elements support the `width` property that can be used to set the width of the entire table or a single table cell. Percentages aren’t fully supported and they’re always converted into absolute units.

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-row-height">

#### Table row height

The `<tr>` element supports the `height` property, which is used to define the height of a table row. The converter always treats this value as the minimum table row height.

<a id="cs/latest/guides/export-to-word/content-formatting.html--table-cell-margins">

#### Table cell margins

Margins of a table cell are specified via the `padding` property on `<th>` and `<td>` elements.

<a id="cs/latest/guides/export-to-word/content-formatting.html--vertical-content-alignment">

#### Vertical content alignment

The `vertical-align` property can be set on `<th>` and `<td>` elements to define how the content of the cell should be aligned vertically. The supported values are `top`, `middle`, and `bottom`.

<a id="cs/latest/guides/export-to-word/content-formatting.html--known-limitations-6">

#### Known limitations

* Table captions are not supported yet.
* Word does not support tables inside list items, so they are moved out of lists.

<a id="cs/latest/guides/export-to-word/content-formatting.html--preformatted-text">

### Preformatted text

The converter supports the `<pre>` element, allowing to display a text in a fixed-width font. This is often used to display code snippets.

```
<pre>
 ________________
/                \
| How about moo? |  ^__^
\________________/  (oo)\_______
                  \ (__)\       )\/\
                        ||----w |
                        ||     ||
</pre>

```

<a id="cs/latest/guides/export-to-word/content-formatting.html--quotations">

### Quotations

The converter supports the `<blockquote>` element, allowing to display its content as a quotation.

Example:

```
<blockquote>
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas eu
 scelerisque tortor. Cras venenatis iaculis velit sit amet sollicitudin.
</blockquote>

```

<a id="cs/latest/guides/export-to-word/content-formatting.html--page-breaks">

### Page breaks

The converter supports the `page` value for the `break-after` and `break-before` properties. Adding this style property to any inline or block HTML element will result in a page break generated before or after the corresponding element.

Page breaks are not supported inside tables.

<a id="cs/latest/guides/export-to-word/content-formatting.html--horizontal-lines">

### Horizontal lines

The converter supports the `<hr>` element, allowing the insertion of horizontal lines in the Word document.

Horizontal lines do not support any styling.

<a id="cs/latest/guides/export-to-word/content-formatting.html--ignored-elements">

### Ignored elements

Any element with the `display` property set to `none` or `contents`, or the `visibility` property set to `hidden` or `collapse` is ignored by the converter.

<a id="cs/latest/guides/export-to-word/content-formatting.html--language">

### Language

The converter supports the `lang` attribute on all supported HTML elements that contain text. In Word, the `lang` attribute specifies the language used for spell-checking the text within the element.

<a id="cs/latest/guides/export-to-word/document-properties.html">source file: "cs/latest/guides/export-to-word/document-properties.html"</a>

## Document properties

Export to Word converter allows for the configuration of various document properties that affect the appearance and behavior of the Word document.

<a id="cs/latest/guides/export-to-word/document-properties.html--document-size">

### Document size

The document size can be specified by selecting one of the predefined values or by setting a custom width and height for the document.

Available document sizes for `config.document.size` are:

| Name      | Width   | Height  |
| --------- | ------- | ------- |
| a3        | 297 mm  | 420 mm  |
| a4        | 210 mm  | 297 mm  |
| a5        | 148 mm  | 210 mm  |
| a6        | 105 mm  | 148 mm  |
| b4        | 250 mm  | 353 mm  |
| b5        | 176 mm  | 250 mm  |
| jb4       | 257 mm  | 364 mm  |
| jb5       | 182 mm  | 257 mm  |
| letter    | 8.5 in  | 11 in   |
| legal     | 8.5 in  | 14 in   |
| statement | 5.5 in  | 8.5 in  |
| executive | 7.25 in | 10.5 in |
| tabloid   | 11 in   | 17 in   |

Default document size is `a4`.

To define a custom page size, set `config.document.size` to an object with `width` and `height` properties set to valid [length values](#cs/latest/guides/export-to-word/document-properties.html--length-values).

Minimum and maximum accepted [length values](#cs/latest/guides/export-to-word/document-properties.html--length-values) for `config.document.size.width` and `config.document.size.height` :

| Unit        | Minimum value | Maximum value |
| ----------- | ------------- | ------------- |
| pixels      | 96            | 2112          |
| centimeters | 2.54          | 55.88         |
| milimeters  | 25.4          | 558.8         |
| inches      | 1             | 22            |

<a id="cs/latest/guides/export-to-word/document-properties.html--document-margins">

### Document margins

Export To Word converter allows for defining the values of the document margins, including `top`, `bottom`, `left`, and `right`. The margin values must follow the format of [length values](#cs/latest/guides/export-to-word/document-properties.html--length-values).

Minimum and maximum accepted [length values](#cs/latest/guides/export-to-word/document-properties.html--length-values) for document margins:

| Unit        | Minimum value | Maximum value |
| ----------- | ------------- | ------------- |
| pixels      | \-2112        | 2112          |
| centimeters | \-55.88       | 55.88         |
| milimeters  | \-558.8       | 558.8         |
| inches      | \-22          | 22            |

Additionally, it is important to note that the sum of the left and right margins should not exceed the width of the document, and the sum of the top and bottom margins should not exceed the height of the document.

Unspecified margins default to 1 inch.

<a id="cs/latest/guides/export-to-word/document-properties.html--document-orientation">

### Document orientation

Document page orientation can be set to either `portrait` or `landscape`.

By default, the orientation of the document is inferred from the width and height of the document. If the width is greater than the height, the document orientation is set to landscape; otherwise, it is set to portrait.

Export to Word converter allows for defining the orientation of the document using the `config.document.orientation` configuration option. When this option is provided, the converter will automatically adjust the width and height of the document to ensure that it is displayed with the desired orientation.

Example of converting a document with a specified orientation:

```
"config" : {
    "document": {
        "size": {
            "width": "5in",
            "height": "8in"
            },
        "orientation": "landscape"
    }
}

```

<a id="cs/latest/guides/export-to-word/document-properties.html--document-language">

### Document language

Export to Word converter allows for defining the language of the document using the `config.document.language` configuration option. This language setting is used by Word to check spelling and grammar mistakes. The language must be specified as a valid RFC 5652 language tag.

<a id="cs/latest/guides/export-to-word/document-properties.html--length-values">

### Length values

Both page size and page margins can be set to custom length values represented as a string containing a number with an attached unit. These values must adhere to the following format:

* Numbers must be written in decimal form.
* The only accepted decimal separator is a period.
* Accepted units are `in`, `cm`, `mm`, and `px`.
* Whitespace between the number and the unit is not allowed.

For example, valid length values include `8.5in`, `2.54cm`, `25.4mm`, and `96px`.

<a id="cs/latest/guides/export-to-word/footnotes.html">source file: "cs/latest/guides/export-to-word/footnotes.html"</a>

## Footnotes

The Export to Word converter supports documents containing CKEditor 5 Footnotes. Editor footnotes are converted to Word endnotes and placed at the end of the document.

<a id="cs/latest/guides/export-to-word/footnotes.html--supported-html">

### Supported HTML

* Note references are represented by `<sup class="footnote"><a href="#${id}"></a></sup>`, where `${id}` is the note’s ID.
* The note list is represented by an `<ol class="footnotes-list"></ol>` element and must be wrapped in a `<div class="footnotes"></div>` container. The list must be the last child of the container.
* Each note is represented by an `<li class="footnote-definition" id="${id}">` element, where `${id}` is the note’s ID. Notes must be direct children of the note list.
* Note content must be wrapped in a `<div class="footnote-content"></div>` element. This wrapper must be the last child of the note’s list item.
* The note list may optionally define the starting value using the `start` attribute and the numbering style using the `list-style-type` CSS property.
* Notes might contain both block-level and inline content.

Example HTML exported by the converter:

```
<p>Lorem ipsum dolor sit amet.<sup class="footnote" id="ref-footnote-0"><a href="#footnote-0">i</a></sup></p>
<div class="footnotes">
    <hr class="footnotes-divider">
    <ol class="footnotes-list" style="list-style-type: lower-roman">
        <li class="footnote-definition" id="footnote-0">
            <a class="footnote-backlink" href="#ref-footnote-0">^</a>
            <div class="footnote-content">
                <p>Endnote content</p>
            </div>
        </li>
    </ol>
</div>

```

<a id="cs/latest/guides/export-to-word/footnotes.html--limitations">

### Limitations

* The type and placement of notes is currently not configurable.
* Backlinks and other editor-only UI helpers are omitted.
* Notes whose content starts with a list have their reference mark rendered inside the list.

For details about the CKEditor 5 Footnotes feature, see the [CKEditor 5 Footnotes documentation](#ckeditor5/latest/features/footnotes.html).

<a id="cs/latest/guides/export-to-word/headers-and-footers.html">source file: "cs/latest/guides/export-to-word/headers-and-footers.html"</a>

## Headers and footers

<a id="cs/latest/guides/export-to-word/headers-and-footers.html--headers">

### Headers

The Export to Word converter supports converting additional HTML and CSS for document headers and footers.

Headers are configurable via `config.headers` configuration property.

| Header type | Description                                                                                  | Config property        |
| ----------- | -------------------------------------------------------------------------------------------- | ---------------------- |
| Default     | Used in place of first, odd and even headers if those specific header types are not defined. | config.headers.default |
| First       | Header rendered on the first page of the document.                                           | config.headers.first   |
| Odd         | Header rendered on odd-numbered pages.                                                       | config.headers.odd     |
| Even        | Header rendered on even-numbered pages.                                                      | config.headers.even    |

<a id="cs/latest/guides/export-to-word/headers-and-footers.html--footers">

### Footers

Footers are configurable via `config.footers` configuration property.

| Footer type | Description                                                                                 | Config property        |
| ----------- | ------------------------------------------------------------------------------------------- | ---------------------- |
| Default     | Used in place of first, odd and even footer if those specific footer types are not defined. | config.footers.default |
| First       | Footer rendered on the first page of the document.                                          | config.footers.first   |
| Odd         | Footer rendered on odd-numbered pages.                                                      | config.footers.odd     |
| Even        | Footer rendered on even-numbered pages.                                                     | config.footers.even    |

Headers and footers do not support the comments and suggestions collaboration features.

<a id="cs/latest/guides/export-to-word/headers-and-footers.html--headers-and-footers-format">

### Headers and footers format

A single header or footer is represented as an object with two properties:

* `html`: Content of a header or footer. This property is required.
* `css`: A CSS style sheet used to style the header or footer content. If this property is not defined, the default formatting will be used.

An example headers and footers configuration, resulting in a converted Word document:

```
"config": {
    "headers" : {
        "first": {
            "html": "<p>My title page header</p>",
            "css": "p { color: red; }"
        },
        "odd": {
            "html": "<p>My odd page header</p>",
            "css": "p { color: green; }"
        },
        "even": {
            "html": "<p>My even page header</p>",
            "css": "p { color: blue; }"
        }
    },
    "footers": {
        "first": {
            "html": "<p>My title page footer</p>",
            "css": "p { color: red; }"
        },
        "odd": {
            "html": "<p>My odd page footer</p>",
            "css": "p { color: green; }"
        },
        "even": {
            "html": "<p>My even page footer</p>",
            "css": "p { color: blue; }"
        }
    },
}

```

<a id="cs/latest/guides/export-to-word/headers-and-footers.html--page-number-and-number-of-pages">

### Page number and number of pages

Headers and footers in the document can display the current page number and the total number of pages. To include this information, you can use the following HTML elements inside the header or footer:

* To show the current page number, use `<span class="pageNumber"></span>`.
* To display the total number of pages, use `<span class="totalPages"></span>`.

An example HTML header, converted to a Word document:

```
<p>
    Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</p>

```

<a id="cs/latest/guides/export-to-word/merge-fields.html">source file: "cs/latest/guides/export-to-word/merge-fields.html"</a>

## Merge fields

The converter provides support for the CKEditor 5 [Merge fields feature](#ckeditor5/latest/features/merge-fields.html). Merge fields allow users to create template fields inside an HTML document, which in the case of Export to Word, can either be converted to Word merge fields or populated with provided data.

Merge fields can be configured via `config.merge_fields` configuration option. [Read about this configuration option in API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Configuration).

<a id="cs/latest/guides/export-to-word/merge-fields.html--word-merge-fields">

### Word merge fields

Word merge fields allow you to effortlessly customize and personalize your documents by dynamically including variable data such as names, addresses, dates, and other unique details from your data source.

This feature is essential for creating tailored communications, whether for letters, emails, labels, envelopes, or directories. By linking your document to various data sources like Excel spreadsheets, Access databases, and Outlook contacts, merge fields pull the exact information you need, ensuring your documents are always up-to-date and accurate. They can save your time by automating the inclusion of personalized details, eliminating the need for manual updates and repetitive data entry, and allowing you to focus on more important tasks.

<a id="cs/latest/guides/export-to-word/merge-fields.html--converting-to-word-merge-fields">

### Converting to Word merge fields

If the merge fields configuration does not include the `data` property, the converter will preserve all merge fields in the generated `.DOCX` file.

Example of converting HTML with merge fields to Word document:

```
{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}"
  }
 }
}

```

```
<p> Hello {NAME}! </p>

```

Word merge fields are used to create form letters, mailing labels, and other documents that are personalized for each recipient. To learn more about using merge fields in Word, see Microsoft’s article on [Mail Merge](https://support.microsoft.com/en-us/topic/how-to-use-the-mail-merge-feature-in-word-to-create-and-to-print-form-letters-that-use-the-data-from-an-excel-worksheet-d8709e29-c106-2348-7e38-13eecc338679).

<a id="cs/latest/guides/export-to-word/merge-fields.html--word-limitations">

#### Word limitations

Some merge field names may contain characters not allowed by Word. As a result of this limitation, when importing the data source, Word will modify it and prompt you to delete or rename incompatible fields during a mail merge.

Consider that we have converted HTML with merge fields to a Word document:

```
{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}"
  }
 }
}

```

```
<p> Hello {FIRST.NAME} {LAST.NAME}! </p>

```

The `.` character is not allowed in Word merge fields data source. When you try to perform a mail merge with a data set including that character, Word will display this dialog:

To avoid this issue, make sure that merge field names do not contain characters that are not allowed by Word. As of now, the following characters are not allowed in merge field names: `.`, `-`, an empty space, starting merge field with a number (e.g. `{1st_name}`).

<a id="cs/latest/guides/export-to-word/merge-fields.html--inserting-data-using-merge-fields">

### Inserting data using merge fields

If the merge fields configuration includes the `data` property, the converter will insert values associated with keys inside the data, which are also placed inside the HTML. Please note that merge fields cannot be used inside HTML attributes or any other part within the markup. They also cannot be used between the opening and closing tags of the `style` tag.

If the provided data is empty or missing values for some field, merge fields without data will be converted to plain text.

The provided data can be in both HTML and plain text formats. Here is an example:

```
{
 "config": {
  "merge_fields": {
   "prefix": "{",
   "suffix": "}",
   "data": {
    "FIRST_NAME": "John",
    "LAST_NAME": "<i>Doe</i>"
   }
  }
 }
}

```

```
<p> Hello {FIRST_NAME} {LAST_NAME}! </p>

```

<a id="cs/latest/guides/export-to-word/multi-level-lists.html">source file: "cs/latest/guides/export-to-word/multi-level-lists.html"</a>

## Multi-level lists

Export to Word supports converting multi-level lists. These lists are a way to organize information using a hierarchy, where main points have subpoints beneath them. Each level contains a reference to its parent level to underline the connection between them. Multi-level lists make it easier to see the relationship between ideas and are often used in outlines or detailed reports.

<a id="cs/latest/guides/export-to-word/multi-level-lists.html--the-multi-level-list-format">

### The multi-level list format

Currently, only one type of multi-level lists is supported: the legal one. It is a special type of multi-level lists commonly used in legal documents to organize information systematically and clearly. These use Arabic numerals (1, 2, 3, etc.) exclusively to ensure consistency, readability, and ease of reference in contracts, statutes, or formal legal writing. Export to Word recognizes the format of [legal lists used in CKEditor 5](#ckeditor5/latest/features/lists/multi-level-lists.html):

1. The `ol` element is used to create a list.
2. The list has the `legal-list` class applied to it.

Example of converting an HTML document with a multi-level list:

```
<h2>List of human spacecraft</h2>
<ol class="multi-level-list legal-list" style="list-style-type: none">
  <li>
    <h2>
      <span class="multi-level-list__marker">1. </span>American spacecraft
    </h2>
    <ol class="multi-level-list legal-list" style="list-style-type: none">
      <li>
        <h3>
          <span class="multi-level-list__marker">1.1. </span>Manned
        </h3>
        <ol class="multi-level-list legal-list" style="list-style-type: none">
          <li><span class="multi-level-list__marker">1.1.1. </span>Mercury</li>
          <li><span class="multi-level-list__marker">1.1.2. </span>Gemini</li>
          <li><span class="multi-level-list__marker">1.1.3. </span>Apollo</li>
          <li>
            <span class="multi-level-list__marker">1.1.4. </span>space shuttle
            <ol
              class="multi-level-list legal-list"
              style="list-style-type: none"
            >
              <li>
                <span class="multi-level-list__marker">1.1.4.1. </span>Columbia
              </li>
              <li>
                <span class="multi-level-list__marker">1.1.4.2. </span
                >Challenger
              </li>
              <li>
                <span class="multi-level-list__marker">1.1.4.3. </span>Discovery
              </li>
              <li>
                <span class="multi-level-list__marker">1.1.4.4. </span>Atlantis
              </li>
              <li>
                <span class="multi-level-list__marker">1.1.4.5. </span>Endeavour
              </li>
            </ol>
          </li>
          <li><span class="multi-level-list__marker">1.1.5. </span>Dragon</li>
          <li>
            <span class="multi-level-list__marker">1.1.6. </span>New Sheppard
          </li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

```

The HTML sample listed above results in the following list in CKEditor 5:

Upon exporting, the resulting document is displayed by Word as follows:

<a id="cs/latest/guides/export-to-word/overview.html">source file: "cs/latest/guides/export-to-word/overview.html"</a>

## Export to Word – overview

CKEditor Cloud Services offers a fast and highly scalable service enabling the user to export documents to a Microsoft Word `.docx` file. The feature is available as a service, making it possible to send an HTML string straight to the Cloud Services server for more advanced use or as a convenient CKEditor 5 WYSIWYG editor plugin for ease of use in less demanding cases.

<a id="cs/latest/guides/export-to-word/overview.html--how-the-export-to-word-feature-works">

### How the Export to Word feature works

The HTML to DOCX converter provides an API for converting HTML documents to Microsoft Word `.docx` files. The service generates a Word file and returns it to the user so they can save it in the `.docx` format on their disk. To integrate the feature into your environment, first, check the [Quick start](#cs/latest/guides/export-to-word/quick-start.html) guide to start using it.

You can also test the feature using [the export to Word demo page](https://docx-converter.cke-cs.com/demo).

<a id="cs/latest/guides/export-to-word/overview.html--the-html-to-docx-converter-options">

### The HTML to DOCX converter options

The following options are available while using the converter service:

* [html](#cs/latest/guides/export-to-word/overview.html--html)
* [css](#cs/latest/guides/export-to-word/overview.html--css)
* [config](#cs/latest/guides/export-to-word/overview.html--config)

<a id="cs/latest/guides/export-to-word/overview.html--html">

#### HTML

Any HTML5-compliant content can be sent to the converter.

<a id="cs/latest/guides/export-to-word/overview.html--css">

#### CSS

A CSS style sheet, that will be used to style the document content during the HTML to DOCX conversion.

The styles can be applied inline directly in the HTML but it is recommended to add these via the `css` option to reduce the size of the HTTP request payload.

<a id="cs/latest/guides/export-to-word/overview.html--config">

#### Config

The `config` option allows adding headers and footers to the generated document and integrating collaboration features. It provides the following options:

* `document` – Set various document properties.
* `headers` – Add headers to the generated Word document.
* `footers` – Add footers to the generated Word document.
* `collaboration_features` – Provide metadata for comments and suggestions contained in the document.
* `base_url` – Set the base URL to use for all relative URLs of images and links.
* `extra_http_headers` – Allow setting extra HTTP headers for resources requiring additional authorization.
* `timezone` – Specify a time zone for dates and times in features that don’t support time zones.
* `merge_fields` – Provide configuration and data for merge fields contained in the document.
* `watermark` – Add a watermark to the generated Word document.

You can learn more about using options in the [converter documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Configuration).

<a id="cs/latest/guides/export-to-word/overview.html--the-export-to-word-plugin">

### The Export to Word plugin

The [Export to Word CKEditor plugin](#ckeditor5/latest/features/converters/export-word.html) allows you to easily print the WYSIWYG editor content to a `.docx` file. When enabled, this feature sends the content of your editor together with the styles that are used to display it to the CKEditor Cloud Services HTML to Word converter service. The service then generates a Word document that the user can download.

Thanks to this plugin, it takes exactly one button click to get a `.docx` file with content formatted the same way as in the CKEditor 5 WYSIWYG editor. An easy solution for integrations, that does not demand editor data to be processed further once it is edited.

<a id="cs/latest/guides/export-to-word/overview.html--stored-data">

### Stored data

The Export to Word service is a service that generates `.docx` files based on the data provided by the customer (HTML, CSS). To perform the conversion, it requires the data sent from the editor or a database, but the service itself is fully stateless.

The data (especially your sensitive data: HTML, CSS, comments, suggestions) is used only during the processing. However, we store some information needed for billing and maintaining our system. We try to reduce stored data to a required minimum and at this moment we store such information as the number and duration of exports, the final document size, the number of unique exports, and statistical data (used features, IP addresses, editor versions).

All logs related to processing requests are saved only in case of unexpected situations and are stored for 14 days. The data in logs includes an error message, stack trace and information about the request.

<a id="cs/latest/guides/export-to-word/quick-start.html">source file: "cs/latest/guides/export-to-word/quick-start.html"</a>

## Export to Word - quick start

The aim of this article is to get you up and running with the Export to Word service.

Follow these steps:

* Subscribe to Export to Word on the [Premium Features Free Trial website](https://portal.ckeditor.com/checkout?plan=free).
* Generate your access credentials in the [Customer Portal](https://portal.ckeditor.com/).
* Configure CKEditor 5.

All the steps are explained in detail below.

<a id="cs/latest/guides/export-to-word/quick-start.html--subscribe-to-ckeditor-cloud-services">

### Subscribe to CKEditor Cloud Services

Create an account in CKEditor Cloud Services by signing up to Export to Word. After signing up, you will receive access to the customer dashboard (Customer Portal).

<a id="cs/latest/guides/export-to-word/quick-start.html--log-in-to-the-customer-portal">

### Log in to the Customer Portal

Log in to the [Customer Portal](https://portal.ckeditor.com) and navigate to “Your products > Cloud Services”.

From the list of available subscriptions in the dashboard choose the Export to Word subscription that you want to manage and press the “Manage” link.

<a id="cs/latest/guides/export-to-word/quick-start.html--using-the-service-with-rest-api">

### Using the service with REST API

The Export to Word service may be used to convert the HTML data into DOCX files. In order to use it, authorization is needed in the form of an authorization token.

The authorization token needs to be passed as a value of the `Authorization` header.

```
{
    'Authorization': 'Your generated authorization token'
}

```

<a id="cs/latest/guides/export-to-word/quick-start.html--generating-the-authorization-token">

#### Generating the authorization token

The authorization token can be generated in two ways:

1. As a value returned from the [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html).
2. Locally created token.

<a id="cs/latest/guides/export-to-word/quick-start.html--creating-access-credentials">

#### Creating access credentials

From the list of environments select the one that you want to manage.

Go to the “Access credentials” tab and click the “Create a new access key” button.

The modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

For your safety, the access key value will disappear in a few seconds. You will be able to display it again by clicking the “Show” button. Make sure to keep the access credentials in a safe place.

Read more about dealing with the credentials in the [Managing access credentials](#cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/export-to-word/quick-start.html--example-request">

#### Example request

Tokens for the HTML to DOCX converter service require passing a payload with the `aud` parameter:

* `aud` – The environment ID.

The `accessKey` value needs to be replaced with your own access key generated before.

The following example presents a request that contains the required `Authorization` header for the HTML to DOCX converter:

```
const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const accessKey = 'iGC6md5EcTG0DDZqEf4m4eytr679z0Ch2gIQuraBPzyWEtTbcpQAqAhA9LxpkDtpn';
const environmentId = 'DO3zekDU3LiJX8GOL2xt';

const token = jwt.sign( { aud: environmentId }, accessKey, { algorithm: 'HS256' } );

const data = {
 html: "<p>I am a teapot</p>",
 css: "p { color: red; }",
 config: {
  headers: {
   default: {
    html: "<h1>Hi! I'm header!</h1>",
    css: "h1 { color: pink; }"
   }
  }
 }
};

const config = {
   headers: {
      'Authorization': token
   },
   responseType: 'arraybuffer'
};

axios.post( 'https://docx-converter.cke-cs.com/v2/convert/html-docx', data, config )
   .then( response => {
      fs.writeFileSync('./file.docx', response.data, 'binary')
   } ).catch( error => {
      console.log( error );
   } );

```

Please refer to the [converter documentation](https://docx-converter.cke-cs.com/docs) to start using the service.

<a id="cs/latest/guides/export-to-word/quick-start.html--using-the-export-to-word-feature-as-a-plugin">

### Using the Export to Word feature as a plugin

In order to use the export to Word feature in your CKEditor 5 build, a token URL is needed for authorization.

<a id="cs/latest/guides/export-to-word/quick-start.html--creating-token-endpoint">

#### Creating token endpoint

Before you can use the feature, you first need to create a [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

<a id="cs/latest/guides/export-to-word/quick-start.html--development-token-endpoint-development-only">

##### Development token endpoint (development only)

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in three simple steps:

1. To work with CKEditor premium features like real-time collaboration, exports or import, you need to create an environment. Environments allow you to create access credentials, manage webhooks, configure features and connect to CKEditor Cloud Services. You may have more than one to serve separate instances or integrations. From the list the environments choose the one that you want to manage.
1. The development token URL will show up in the “Development token URL” section:

<a id="cs/latest/guides/export-to-word/quick-start.html--writing-your-own-token-endpoint-production">

##### Writing your own token endpoint (production)

To write your own [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html), you need to create access credentials for the selected environment by going to the “Access credentials” tab and clicking the “Create a new access key” button.

Read more in the [Creating access credentials](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/export-to-word/quick-start.html--integrating-the-export-to-word-plugin-with-the-application">

#### Integrating the Export to Word plugin with the application

To install the plugin into your WYSIWYG editor, use the [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate a custom CKEditor 5 build with the plugin enabled. Alternatively, refer to the [installation guide](#ckeditor5/latest/features/converters/export-word.html--installation) in the plugin documentation to do it on your own.

Configure the plugin using the token generated earlier, pasting the link in the configuration (see [CloudServicesConfig](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html)):

```
 ClassicEditor
  .create( document.querySelector( '#editor' ), {
   exportWord: {
    tokenUrl: 'https://example.com/cs-token-endpoint',
   }
  } )
  .then( ... )
  .catch( ... );

```

This is all. At this point, the export to Word feature will be automatically enabled in your application.

Refer to the [CKEditor 5 export to Word guide](#ckeditor5/latest/features/converters/export-word.html) if you need more information on integrating Export to Word with your WYSIWYG editor!

<a id="cs/latest/guides/export-to-word/styles.html">source file: "cs/latest/guides/export-to-word/styles.html"</a>

## Styles

There are several ways to apply content formatting in Word. The first one is inline styling that is applied via various toolbar buttons and dropdowns. This formatting happens “in place”, and it always takes precedence over any other types of formatting.

Styles are the more advanced way to format large portions of a document. This kind of formatting is applied to specific areas, like titles, headers, regular paragraphs, lists etc. and it is global, i.e. it is applied to the whole Word document.

The last way to style the document content is the default document properties. They are applied via Format options, similarly to some inline styles, except for choosing an option to apply them as the default formatting instead of the inline one.

The Export to Word converter is able to recognize all these styling methods and apply them by converting HTML and CSS into fully formatted Word documents.

<a id="cs/latest/guides/export-to-word/styles.html--content-formatting">

### Content formatting

For a current list of all supported features that can be converted correctly by the Export to Word feature, please see [dedicated guide](#cs/latest/guides/export-to-word/content-formatting.html).

<a id="cs/latest/guides/export-to-word/styles.html--word-styles">

### Word Styles

Word Styles are pre-defined sets of formatting options that can be applied to elements in a Microsoft Word document to ensure consistency and improve the appearance of the document. These styles can include formatting for font type, size, color, alignment, spacing, and other attributes.

The list of commonly used styles is available in the Microsoft Word “Home” tab toolbar:

To support this feature in the Export to Word, the converter has been equipped with a mechanism to automatically detect Word Styles based on the document’s style. This mechanism checks the styles applied to selected HTML elements and generates the appropriate formatting for the corresponding styles.

The following styles are applied to generate specific formatting in the Export to Word converter:

* Styles applied to `<h1>` to `<h6>` elements are used to generate the `Heading 1` to `Heading 6` styles formatting.
* Styles applied to the `<pre>` element are used to generate the `Plain Text` style formatting.
* Styles applied to the `<blockquote>` element are used to generate the `Quote` style formatting.
* Styles applied to the `<code>` element are used to generate the `Code` style formatting.
* Styles applied to the `<a>` element with the `href` attribute are used to generate the `Hyperlink` style formatting.

For the `Heading 1` to `Heading 6`, `Plain Text` and `Quote` styles converter supports all paragraph and text formatting options described in [content formatting section](#cs/latest/guides/export-to-word/content-formatting.html).

For `Code` and `Hyperlink` styles converter supports all text formatting options described in [content formatting section](#cs/latest/guides/export-to-word/content-formatting.html).

Example of converting HTML that produces `Heading 2` style inside converted Word document:

```
<h2>Heading 2 </h2>

```

```
h2 {
 font-size: 24px;
 font-family: Arial;
 font-weight: bold;
 font-style: italic;
 color: rgb(0, 0, 255);
}

```

<a id="cs/latest/guides/export-to-word/styles.html--default-styles">

### Default styles

Word allows changing the default formatting of documents to style it in a specific way. You can apply the same style to the whole Word document without the need to apply it manually. For example, you can open the Format menu, choose the Font option and then change some formatting such as font size and font family. After that, choose the “Default…” option and confirm the second dialog:

The Export to Word converter can recognize styles that are applied to a aragraph element (`<p>`) and generate the default properties based on them. The following CSS properties are recognized:

* `font-family`: Specifies the font family for the text.
* `font-size`: Sets the size of the font.
* `color`: Defines the color of the text.
* `margin-top`, `margin-bottom`, `margin-left`, `margin-right`: Controls the spacing around the element.
* `text-align`: Aligns the text.
* `line-height`: Sets the height of each line of text.

Due to how Word handles default styles, default paragraph and text styles can be overwritten by other elements with higher priority. Usually, the priority of default styles is the lowest, so elements like table cells take precedence over default styles:

```
<p>Paragraph with default styles</p>
<table>
    <tr>
        <th>Header 1</th>
        <th>Header 2</th>
    </tr>
    <tr>
        <td>
            <p>Paragraph inside table cell</p>
        </td>
        <td>Row 1, Cell 2</td>
    </tr>
</table>

```

```
p {
 color: blue;
}
table {
    color: red;
}

```

<a id="cs/latest/guides/export-to-word/watermark.html">source file: "cs/latest/guides/export-to-word/watermark.html"</a>

## Watermark

Export to Word supports configuration of the watermark. It allows you to add a semi-transparent image watermark to each page of the exported Word document. It can be a logo, a symbol, or any custom image that you choose. This feature may add a layer of visual branding, copyright protection, or decorative design for your documents. It is particularly useful for professional documents, such as reports, contracts, or marketing materials.

<a id="cs/latest/guides/export-to-word/watermark.html--watermarks-format">

### Watermarks format

The watermark configuration is represented as an object containing 4 properties:

* `source`: A source of the image used for the watermark. It must be a valid URL. This property is required.
* `width`: A string value representing the width of the watermark. This property is optional. If not specified, the width will be automatically calculated based on the aspect ratio of the image and the specified height. If neither width nor height are provided, the original image dimensions will be used to determine the width.
* `height`: A string value representing the height of the watermark. This property is optional. If not specified, the height will be automatically calculated based on the aspect ratio of the image and the specified width. If neither height nor width are provided, the original image dimensions will be used to determine the height.
* `washout`: A boolean that determines whether the washout effect should be applied on watermark (changes brightness and contrast on the generated watermark). This property is optional, and the default value is `false`.

See [images content formatting documentation](#cs/latest/guides/export-to-word/content-formatting.html--images) for the list of allowed URL schemes and supported image formats for the `source` property. Note that the [base\_url option](https://docx-converter.cke-cs.com/v2/convert/docs#section/Export-to-Word/Configuration) does not work on this property.

Width and height values must follow the format of [length values](#cs/latest/guides/export-to-word/document-properties.html--length-values). Each value must be greater than or equal to 1 inch and less than or equal to 22 inches.

Example of converting a document with a specified watermark:

```
{
 "config": {
  "watermark": {
    "source": "https://placeholder.com/300",
    "width": "400px",
    "height": "400px"
  }
 }
}

```

```
<p> Some content </p>

```

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html">source file: "cs/latest/guides/import-from-word/advanced-table-formatting.html"</a>

## Advanced Table Formatting

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--overview">

### Overview

Advanced Table Formatting is a feature that enables you to conditionally modify the appearance of certain table cells depending on their position within a table. For example, you can change the background color of even rows or make text in the topmost row bold. This can greatly improve the readability of your tables and draw attention to certain parts of the table.

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--usage">

### Usage

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--built-in-styles">

#### Built-in styles

Advanced Table Formatting can be added to a table using table styles. You can either choose one of the many built-in styles or create your own. To do that, switch to the **Table Design** tab. In the gallery, some of the available table styles are displayed. When you hover the cursor over the gallery, the arrow shows at the bottom. Click it to expand the view and see all table styles.

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--custom-formatting">

#### Custom Formatting

To create a custom table style, choose the **New Table Style…** option from the expanded gallery view:

Tables have several regions that formatting can be applied to:

* Header row
* Total row
* First column
* Last column
* Banded rows and columns
* Corner table cells

You can select the region that you want to style using the first dropdown from the **Formatting** section.

Additionally, each table can toggle whether the formatting of a particular region should be applied to it using checkboxes in the **Table Design** tab.

By default, the formatting of the following regions is enabled:

* Header row
* First column
* Banded rows

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--banded-rows-and-columns">

#### Banded Rows and Columns

In Word, each table consists of bands, which represent groups of consecutive rows and columns. Bands can be either odd or even, depending on their position in a series of sibling bands. This means that, for example, we can use them to create a table with alternate row colors.

By default, Word sets the size of bands to 1, but it can be modified. Taking the table from the previous image as an example, when we change its band size of rows to 2, its rows are divided into groups of two, and the light background color is applied only to every other group:

You can modify the band size in the same dialog box that is used to create a new table style. From the **Format** dropdown located at the bottom, choose the **Banding…** option.

This opens the **Stripes** dialog box, where you can change the size of the row and column bands separately.

<a id="cs/latest/guides/import-from-word/advanced-table-formatting.html--conversion-output">

### Conversion Output

The HTML produced for Advanced Table Formatting is independent of Word applications and HTML consumers. Table formatting is inlined with HTML and can be displayed by modern browsers or rich text editors that support table formatting, like CKEditor 5\. This approach eliminates the need for the HTML consumer to implement any specific logic to understand the HTML produced by the Import from Word feature.

Let’s consider a table where the top row has a blue background and the text in it is white. All the other rows have a white background and the text in them is black.

The HTML markup of the first table row after the conversion is as follows:

```
<tr>
    <td style="background-color: #1f4e79">
        <p>
            <span style="color: #ffffff"><strong>Lorem</strong></span>
        </p>
    </td>
    <td style="background-color: #1f4e79">
        <p>
            <span style="color: #ffffff"><strong>Ipsum</strong></span>
        </p>
    </td>
    <td style="background-color: #1f4e79">
        <p>
            <span style="color: #ffffff"><strong>Dolor</strong></span>
        </p>
    </td>
</tr>

```

Note that the formatting was inlined into the whole table, each table row, and each table cell. The converter does not use CSS pseudo-classes, such as `:nth-child()`, to represent the Advanced Table Formatting.

<a id="cs/latest/guides/import-from-word/collaboration-features.html">source file: "cs/latest/guides/import-from-word/collaboration-features.html"</a>

## Supported collaboration features

The Import from Word converter supports Word’s collaboration features, namely the comments and track changes. The comments feature lets you add a notice about a selected part of the content, whereas track changes allows proposing a change inside the content, like deletion, insertion, or replacement of a selected part of the content.

Both features are also implemented by CKEditor 5, so make sure to read [CKEditor 5 comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [CKEditor 5 track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) guides to learn more.

Note that despite producing compatible content with CKEditor 5 collaboration features, the Import from Word converter is technology-agnostic and can be used with custom integrations on your end - as long as it supports the same content format.

Learn how these are turned into HTML properties and supported by CKEditor 5 from this guide.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--comments">

#### Comments

Comments are an advanced feature of Word that is supported by the Import from Word feature with full compatibility with [CKEditor 5 comments](#ckeditor5/latest/features/collaboration/comments/comments.html). You can add a comment to a Word document by selecting some content and choosing the New Comment option from the Insert tab in the ribbon, or just by using the context menu that can be opened by right-clicking the selected content.

Comments are fully preserved by Import From Word by producing HTML that is compatible with CKEditor 5 and returning comments definitions, that can be integrated both by using [Import from Word CKEditor 5 plugin](#ckeditor5/latest/features/converters/import-word/import-word.html) or implementing custom comments integration.

To enable comments conversion using REST API, pass information [about user ID](#cs/latest/guides/import-from-word/collaboration-features.html--collaboration-authors-and-users) and `collaboration_features.comments` property in the request body:

```
const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    }
};

```

An example payload that will be returned for a simple comment shown in the above screenshots looks like this:

```
{
  "html": "<p><comment-start name=\"thread-id\"></comment-start>Hello, World!<comment-end name=\"thread-id\"></comment-end></p>",
  "comment_threads": [
    {
      "thread_id": "thread-id",
      "is_resolved": false,
      "comments": [
        {
          "author": "John",
          "content": "<p>Comment 1</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        },
        {
          "author": "Neil",
          "content": "<p>Comment 2</p>",
          "created_at": "2022-09-19T15:05:00Z",
          "is_resolved": false,
        }
      ]
    }
  ]
}

```

The `comment_threads` JSON property includes the full list of comments that were found in the document, grouped by the comment thread ID. Each comment includes the content of the comment in HTML format and information about the original `author` of the comment.

The comments feature is fully supported by CKEditor 5 and only requires enabling the [CKEditor 5 comments](#ckeditor5/latest/features/collaboration/comments/comments.html) and [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) plugins.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--resolved-comments">

##### Resolved comments

Resolving comments in Word is a way to indicate that a particular comment has been addressed and is no longer a concern. To resolve a comment, a user can simply right-click on it and select “Resolve Comment.” The comment will then be grayed out and a checkmark will appear next to it.

Import from Word returns information about resolved comments within the returned payload. The `is_resolved` property indicates whether a comment has been resolved by a user. This property can be found both on the comment thread and on a single comment. A comment thread will only be considered resolved when all comments within the thread have been marked as resolved.

Resolved comments are supported by the [CKEditor 5 Comments](#ckeditor5/latest/features/collaboration/comments/comments.html) feature.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--comments-styles">

##### Comments styles

By default, all styling that was applied to comments will be preserved. If you would like to limit comments formatting applied during the conversion, `formatting.comments` will come in handy.

The option can use one of these values:

* `full` – default value, enables all comments styling,
* `basic` – preserves only bold, italic, underline and strikethrough styles,
* `none` – no styles will be preserved.

```
const config = {
    collaboration_features: {
        user_id: 'user-id',
        comments: true
    },
    formatting: {
        comments: 'basic'
    }
};

```

<a id="cs/latest/guides/import-from-word/collaboration-features.html--track-changes">

#### Track changes

Track changes is another advanced feature that is also compatible with the [CKEditor 5 track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html). To start tracking changes in Word, select the Review tab from the ribbon and then enable option Track Changes. After that, any changes applied to the document will be tracked.

At the moment, the Import from word supports text insertions and deletions, including changes within tables, lists and images.

Additionally, Word documents can include move suggestions when a part of the content is moved to a different location in the document. These suggestions are represented by a pair of corresponding deletion and insertion suggestions, simplifying their overall structure, without losing any information.

To enable track changes conversion using REST API, pass information [about user ID](#cs/latest/guides/import-from-word/collaboration-features.html--collaboration-authors-and-users) and `collaboration_features.track_changes` property in the request body.

```
const config = {
    collaboration_features: {
        user_id: 'user-id',
        track_changes: true
    }
};

```

An example payload that will be returned for a simple suggestion:

```
{
  "html": "<p>Hello, <suggestion-start name=\"suggestion-id:user-id\"></suggestion-start>World!<suggestion-end name=\"suggestion-id:user-id\"></suggestion-end></p>",
  "suggestions": [
    {
        "id": "suggestion-id",
        "type": "insertion",
        "author": "John",
        "created_at": "2022-09-19T15:05:00Z"
    }
  ]
}

```

The `suggestions` JSON property includes the full list of suggestions that were found in the document. Each suggestion includes the unique ID of the suggestion that is both applied to the suggestion definition and HTML content, the type of the suggestion (`insertion`/`deletion`) and information about the original `author` of the suggestion.

The track changes feature is fully supported by CKEditor 5 and only requires enabling the [CKEditor 5 track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) and [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) plugins.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--timezone">

##### Timezone

The Word track changes feature does not support the UTC format for suggestions creation dates. To calculate them properly we use the timezone data supplied to the converter via `config.timezone` ([read more about this configuration option in API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Import-from-Word)).

<a id="cs/latest/guides/import-from-word/collaboration-features.html--known-limitations">

##### Known limitations

* Limited support for tracking changes of HTML block elements like tables and lists to the text content of these elements.
* No support for formatting suggestions, like applying bold to the text or changing a paragraph to the list.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--disabled-track-changes">

#### Disabled Track Changes

If the document includes some suggestions but the Track Changes feature is disabled by the `collaboration_features.track_changes` configuration option, all track changes will be treated as applied. As an example, if a user has a document with a text insertion suggestion, that text will be applied to the HTML as a regular text. The deletion suggestions work the same way – if some content is suggested as deleted, it will be removed from the HTML.

That behavior ensures the least possible content loss during the conversion process, making sure that even if you do not enable the track changes feature, you will still get the most out of the Import from Word converter.

<a id="cs/latest/guides/import-from-word/collaboration-features.html--collaboration-authors-and-users">

#### Collaboration authors and users

Please notice that authors imported from Word, also visible in CKEditor 5 as users, are directly loaded from the `.docx` file. They are not the same as users created in Cloud Services.

The Word documents can be manipulated by 3rd party authors, posing a potential security threat should they be connected automatically with the Cloud Services users. Therefore, the CKEditor 5 Collaboration Features ensure that the author of the comment or suggestion is only used for display purposes. The actual user who is connected to the CKEditor 5 Collaboration Features is the one who is logged in to the Cloud Services.

Let’s consider such a situation: there is a document edited in CKE5 with a few comments. The document is exported to Word and then imported back to the CKEditor 5\. In this case, the connection between comments’ authors and Cloud Services users is lost, as the CKEditor 5 can’t guess which user is the author of the comment only based on the provided Word file.

<a id="cs/latest/guides/import-from-word/content-formatting.html">source file: "cs/latest/guides/import-from-word/content-formatting.html"</a>

## Supported content formatting features

Listed below are all content formatting features that are currently supported by the Import from Word converter.

<a id="cs/latest/guides/import-from-word/content-formatting.html--inline-formatting">

### Inline formatting

Support for inline formatting includes conversion of inline styling (from UI toolbar buttons), styles, and default document properties.

The inline formatting is generated as native HTML tags (e.g. `<strong>` for bold text) or as `<span>` tags with proper CSS styling declarations. Applying multiple inline styles to the same content will produce nested HTML, like:

```
<p>
    <span style="font-size: 21.33px; font-family: Georgia, serif">
        <i>
            <u>Hello, World!</u>
        </i>
    </span>
</p>

```

All inline content is placed inside a paragraph (`<p>`) element.

<a id="cs/latest/guides/import-from-word/content-formatting.html--basic-styling">

#### Basic styling

Provides support for basic inline styling, including bold, italics, underline, and strikethrough.

Basic styles are converted to semantic HTML tags, making the content more accessible and SEO-friendly.

| Feature name  | Markup   |
| ------------- | -------- |
| Bold          | <strong> |
| Italics       | <i>      |
| Underline     | <u>      |
| Strikethrough | <s>      |

<a id="cs/latest/guides/import-from-word/content-formatting.html--custom-underline-styling">

#### Custom underline styling

The Import from Word converter is able to preserve custom underline styling, including line style, color, and thickness.

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations">

##### Known limitations

* Currently, the supported CSS does not offer equivalents for every line type currently found in Word. Some of these styles had to be adjusted to offer the best compatibility.

<a id="cs/latest/guides/import-from-word/content-formatting.html--font-styles">

#### Font styles

Provides support for different font styles, including font family, font size, font color, background color, and many more.

| Feature name    | Markup                                       |
| --------------- | -------------------------------------------- |
| Font size       | <span style="font-size: 16px">               |
| Font family     | <span style="font-family: 'Comic Sans MS'">  |
| Font color      | <span style="color: #ff0000">                |
| Font background | <span style="background-color: #00ffff">     |
| Subscript       | <sub>                                        |
| Superscript     | <sup>                                        |
| Small caps      | <span style="font-variant-caps: small-caps"> |
| All caps        | <span style="text-transform: uppercase">     |
| Letter spacing  | <span style="letter-spacing: 1px">           |
| Font stretching | <span style="font-stretch: 125%">            |

<a id="cs/latest/guides/import-from-word/content-formatting.html--links">

#### Links

Provides support for links.

| Feature name | Markup                          |
| ------------ | ------------------------------- |
| Link         | <a href="https://cksource.com"> |

Links can be fully styled just as any other inline content.

```
<p>
    <a href="https://cksource.com">
        <span style="color: #f12ec5; font-size: 26.67px;">
            <strong>
                <u>Colorful link!</u>
            </strong>
        </span>
    </a>
</p>

```

<a id="cs/latest/guides/import-from-word/content-formatting.html--text-language">

#### Text language

Language of text is outputted as RFC 5646 value in `lang` attribute for specific part of text.

To ensure that [CKEditor 5 Text Part Language](#ckeditor5/latest/features/language.html) properly recognizes the languages returned by the converter, make sure that the format of language tags configured in your editor matches exactly with the format of language tags returned by the converter.

<a id="cs/latest/guides/import-from-word/content-formatting.html--hidden-text">

#### Hidden text

Hidden text is supported by simply not outputting any HTML markup for it.

<a id="cs/latest/guides/import-from-word/content-formatting.html--images">

#### Images

Import from Word can recognize both embedded images in the document and images that come from external sources.

Images are converted to `<img>` tags with a proper `src` attribute.

| Feature name | Markup                                     |
| ------------ | ------------------------------------------ |
| Image        | <img src="https://cksource.com/image.png"> |

Images that include an external hyperlink are converted to inline images, wrapped in an anchor (`<a>`) tag.

Additionally, the converter supports these Word features:

| Feature name     | Markup                                               |
| ---------------- | ---------------------------------------------------- |
| Alternative text | <img alt="Alternative text" src="..." />             |
| Image height     | <img style="height: 100px" height="100" src="..." /> |
| Image width      | <img style="width: 100px" width="100" src="..." />   |

<a id="cs/latest/guides/import-from-word/content-formatting.html--image-positioning">

##### Image positioning

The converter supports the basic positioning of images:

* Distance from the top and left edges or margins of the page is translated to appropriate CSS margins and, additionally, such images get the `float: left` CSS property.
* Horizontally aligned images are converted to images with an appropriate value of the `float` CSS property or, in the case of centered images, to images centered by the `margin-left: auto` and `margin-right: auto` CSS properties.

Moreover, setting an image behind or in front of text works by applying the appropriate value of the `z-index` CSS property to the image. To fully support the behind-the-text position, the container (e.g. CKEditor 5 editor) must have a transparent background. For CKEditor 5 it can be achieved by the following CSS code:

```
.ck-editor__editable {
    background-color: transparent;
}

```

<a id="cs/latest/guides/import-from-word/content-formatting.html--rotation">

##### Rotation

Image rotation, both in 2D and 3D, is supported along with the Word’s built-in camera presets. When using the camera presets, only those with rotation angles defined are outputted.

| Feature name   | Markup                                              |
| -------------- | --------------------------------------------------- |
| Image rotation | <img style="transform: rotateZ(90deg)" src="..." /> |

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-2">

##### Known limitations

* Positioning and text wrapping settings are supported only on a basic level.
* Horizontal alignment does not work if the image is positioned behind or in front of the text.
* Horizontal centering does not work if the image is also vertically positioned.
* Captions are currently converted to regular paragraphs.
* Image perspective is not supported.

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-for-inline-formatting">

#### Known limitations for inline formatting

* Due to their complicated representation in Word documents, tab characters are always converted to 4 spaces.

<a id="cs/latest/guides/import-from-word/content-formatting.html--block-formatting">

### Block formatting

Block-level Word features are converted to proper block-level HTML elements to represent the same semantic meaning and visual appearance. Some elements like images can be either inline or block-level, depending on their position in the document.

Similarly to inline formatting, block formatting can be directly applied to the Word content and (depending on the feature) defined as inline styling or a separate style, or it can be part of default document properties.

<a id="cs/latest/guides/import-from-word/content-formatting.html--paragraphs">

#### Paragraphs

Any text that occurs in the document, regardless of its styling, is placed inside a paragraph element. Paragraphs are converted to `<p>` tags and can be nested inside table cells and list items.

```
<p>
    Representative paragraph.
</p>

```

Paragraphs in Word can additionally be styled with the following features:

| Feature name           | Markup                                              |
| ---------------------- | --------------------------------------------------- |
| Text alignment         | <p style="text-align: right">                       |
| Indentation            | <p style="margin-left: 48px">                       |
| First line indentation | <p style="text-indent: 190px">                      |
| Hanging indentation    | <p style="margin-left: 190px; text-indent: -190px"> |
| Line height            | <p style="line-height: 1.5">                        |
| Paragraph spacing      | <p style="margin-top: 20px; margin-bottom: 10px">   |
| Paragraph borders      | <p style="border-top: 1px solid #000000">           |
| Background color       | <p style="background-color: #ffc000">               |

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-3">

##### Known limitations

* The “at least” line height type is treated the same as the “exact” one.
* Spacing between paragraphs of the same style is always preserved, even when explicitly disabled.

<a id="cs/latest/guides/import-from-word/content-formatting.html--headings">

#### Headings

Headings in Word documents are represented by paragraphs with a special formatting property called “outline level”. It can be applied either by using styles, such as the built-in “Heading 1” style, or by paragraph formatting.

This property determines into what heading a paragraph will be converted. The converter only supports headings from `<h1>` up to `<h6>`. If there are some headings imported outside this span, they will be clamped to the closest respective level (i.e. levels larger than 1 will be turned into `<h1>` while levels below 6 will be rendered as `<h6>`). Otherwise, they act like paragraphs.

Styles that can be applied to paragraphs can also be applied to headings.

```
<h1>Heading 1</h1>
<h2 style="color: #ffc000">Colored heading 2</h2>

```

<a id="cs/latest/guides/import-from-word/content-formatting.html--lists">

#### Lists

Import from Word support both ordered and unordered lists that are available in Word, converting them to proper HTML elements. List items text content is always wrapped within a `<p>` element.

The most basic list structure of an unordered list is shown below:

```
<ul style="list-style-type: disc">
  <li><p>List item 1</p></li>
  <li>
    <p>List item 2</p>
    <ul style="list-style-type: circle">
      <li><p>List item 3</p></li>
    </ul>
  </li>
</ul>

```

And the basic structure for an ordered list:

```
<ol style="list-style-type: decimal">
  <li><p>List item 1</p></li>
  <li>
    <p>List item 2</p>
    <ol style="list-style-type: lower-latin">
      <li><p>List item 3</p></li>
    </ol>
  </li>
</ol>

```

The converter supports multi-level lists that do not include some intermediary levels. Such lists are created by indenting list items. As an example, we can have a list that, after the first level, skips the second one and goes directly to the third one. This is supported by the converter, and the result will be the following:

```
<ol style="list-style-type: decimal">
  <li>
    <p>Level 1</p>
    <ul style="list-style-type: none">
      <li>
        <ol style="list-style-type: lower-roman">
          <li><p>Level 3</p></li>
        </ol>
      </li>
    </ul>
  </li>
</ol>

```

Ordered lists can start with a different number than 1 by utilizing the available `start` HTML attribute that matches the proper list level from a Word document:

```
<ol start="4" style="list-style-type: decimal">
  <li><p>Item 4</p></li>
  <li><p>Item 5</p></li>
  <li><p>Item 6</p></li>
</ol>

```

Due to the fact that Word lets the user set any character as a marker in unordered lists, the converter will first try to recognize the marker character and match it to supported ones as closely as possible. If the used marker cannot be recognized, it will fall back to the `disc` list style type.

* Default supported unordered list styles are: `disc`, `circle`, `square`, and `none`.
* Default supported ordered list styles are: `decimal`, `lower-latin`, `lower-roman`, and `decimal-leading-zero`.
* Other numbering types, such as Hebrew or Thai, are also supported. However, some of them do not have a CSS counterpart, and they are converted to some other numbering that is available in CSS. An example of such numbering is the numbering using the Russian alphabet that is converted to `lower-latin`.

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-4">

##### Known limitations

* Due to differences between built-in DOCX and CSS numbering definitions, some numbering types may have discrepancies. The extent of those discrepancies depends on specific numbering, so for some lists, the first list item with different numbering may be the thousandth one, whereas for other ones the numbering may start being different at around the 30th item.
* Custom list markers are not supported. This applies to some built-in list styles, and, in general, to markers that cannot be represented by the built-in CSS list style types.
* Marker detection, due to DOCX representation of unordered lists, depends on fonts used for list markers and cannot be generalized. This means that there is always a possibility of producing an invalid marker.
* Indentation of list items is not supported right now.

<a id="cs/latest/guides/import-from-word/content-formatting.html--tables">

#### Tables

Tables are represented as `<figure>` elements with a `<table>` element inside, to keep the same content semantics as CKEditor 5.

Every `figure` element includes a `table` class, giving the integrator an easy way to apply custom styles to all tables, e.g. to reposition them inside the document.

An example of a simple table that will be output by the converter (styles skipped for clarity):

```
<figure class="table">
  <table>
    <tbody>
      <tr>
        <td>
          <p>Cell 1</p>
        </td>
        <td>
          <p>Cell 2</p>
        </td>
      </tr>
    </tbody>
  </table>
</figure>

```

Tables support most features that are available in Word, including:

| Feature name              | Markup                                              |
| ------------------------- | --------------------------------------------------- |
| Table / cell width        | <td style="width: 100px;">                          |
| Table / cell height       | <td style="height: 20px;">                          |
| Cell merging              | <td colspan="2">                                    |
| Cell padding              | <td style="padding-top: 20px">                      |
| Cell spacing              | <table style="border-spacing: 10px">                |
| Cell’s vertical alignment | <td style="vertical-align: top">                    |
| Table background color    | <table style="background-color: #f4b083;">          |
| Cell background color     | <td style="background-color: #f4b083;">             |
| Table border style        | <table style="border-top: 1px solid #f4b083;">      |
| Cell border style         | <td style="border-top: 1px solid #f4b083;">         |
| Table header              | <th scope="col">                                    |
| Table alignment/floating  | <figure style="margin-left: auto; margin-right: 0"> |

Table nesting is properly supported by the converter, it’s possible to have multiple tables inside each other. Table captions are converted to normal paragraphs to keep the same representation of the caption as in Word.

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-5">

##### Known limitations

* Conditional table formatting is not supported.
* Captions are currently converted to regular paragraphs.
* Some border styles may not be properly resolved in the browser, as the resolution of border conflicts differs between HTML and Word.

<a id="cs/latest/guides/import-from-word/content-formatting.html--page-breaks">

#### Page breaks

Page breaks in Word can be added in two ways: by using the “Page Break” button in the toolbar, or by applying a special “Page break before” paragraph formatting that adds a page break before the paragraph.

Both those methods are supported by Import from Word, and produce the following HTML:

```
<div class="page-break" style="page-break-after: always">
  <span style="display: none">&nbsp;</span>
</div>

```

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-6">

##### Known limitations

* Page breaks applied through the paragraph formatting are not supported inside tables.

<a id="cs/latest/guides/import-from-word/content-formatting.html--horizontal-lines">

#### Horizontal lines

Horizontal lines in Word are, similarly to HTML, designed to guide the flow of a text or to separate parts of a document. Import from Word properly recognizes and converts horizontal lines to semantically correct `<hr>` elements.

```
<p>Paragraph 1</p>
<hr />
<p>Paragraph 2</p>

```

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-7">

##### Known limitations

* Horizontal line styling is not supported at the moment.

<a id="cs/latest/guides/import-from-word/content-formatting.html--complex-objects">

#### Complex objects

Word incorporates more complex objects like a table of contents, text boxes, citation fields, etc. Import from Word attempts to support all of them, but some of them may not be converted properly due to the limitations of HTML and CSS itself.

<a id="cs/latest/guides/import-from-word/content-formatting.html--known-limitations-8">

##### Known limitations

* The content of a table of contents is preserved, but it does not support content bookmarks.
* Form objects: only the text and styling are retained.

<a id="cs/latest/guides/import-from-word/footnotes.html">source file: "cs/latest/guides/import-from-word/footnotes.html"</a>

## Footnotes

The Import from Word converter transforms Word footnotes and endnotes into CKEditor 5 footnotes (rendered as endnotes).

<a id="cs/latest/guides/import-from-word/footnotes.html--conversion-output">

### Conversion output

* The output contains a single consolidated note list. When multiple note lists are present in the source document, their entries are merged in the order in which note references appear in the document content. The consolidated list is placed at the end of the document.
* Footnote and endnote formatting is resolved independently based on the document’s final section. The resolved format corresponding to the type of the first note reference (footnote or endnote) is then used in the output.
* Both block-level and inline content within notes is preserved during conversion.

An example of HTML imported from a Word document:

```
<p>Lorem ipsum dolor sit amet.<sup class="footnote" id="ref-footnote-0"><a href="#footnote-0"></a></sup></p>
<div class="footnotes">
    <hr class="footnotes-divider">
    <ol class="footnotes-list" style="list-style-type: lower-roman">
        <li class="footnote-definition" id="footnote-0">
            <a class="footnote-backlink" href="#ref-footnote-0"></a>
            <div class="footnote-content">
                <p>Endnote content</p>
            </div>
        </li>
    </ol>
</div>

```

<a id="cs/latest/guides/import-from-word/footnotes.html--limitations">

### Limitations

* The placement of notes is currently not configurable.
* Notes whose content starts with a list have their reference mark rendered outside the list in HTML.

For details about the CKEditor 5 Footnotes feature, see the [CKEditor 5 documentation](#ckeditor5/latest/features/footnotes.html).

<a id="cs/latest/guides/import-from-word/headers-and-footers.html">source file: "cs/latest/guides/import-from-word/headers-and-footers.html"</a>

## Headers and footers

The Import from Word converter supports converting content of Word’s headers and footers into additional HTML.

<a id="cs/latest/guides/import-from-word/headers-and-footers.html--headers-and-footers-format">

### Headers and footers format

A single header or footer is represented as an object with single property:

* `html`: Content of a header or footer.

Following types of headers and footers may be returned as a result of conversion:

| Type    | Description                                                                                               |
| ------- | --------------------------------------------------------------------------------------------------------- |
| Default | Used in place of first, odd and even header/footer if those specific header/footer types are not defined. |
| First   | Header/footer rendered on the first page of the document.                                                 |
| Odd     | Header/footer rendered on odd-numbered pages.                                                             |
| Even    | Header/footer rendered on even-numbered pages.                                                            |

An example Word document with headers and footers and converted result:

```
// ...rest of the response
"headers" : {
    "first": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #ff0000; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My title page header
                    </span>
                </p>
        ",
    },
    "odd": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #3a7c22; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My odd page header
                    </span>
                </p>
        ",
    },
    "even": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #0f4761; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My even page header
                    </span>
                </p>
        ",
    }
},
"footers": {
    "first": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #ff0000; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My title page footer
                    </span>
                </p>
        ",
    },
    "odd": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #3a7c22; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My odd page footer
                    </span>
                </p>
        ",
    },
    "even": {
        "html": "<p style=\"margin-top: 0px; margin-bottom: 0px; line-height: 1\">
                    <span
                        style=\"color: #0f4761; font-size: 16px; font-family: Aptos, sans-serif\"
                        lang=\"en-US\"
                        >My even page footer
                    </span>
                </p>
        ",
    }
}

```

<a id="cs/latest/guides/import-from-word/headers-and-footers.html--page-number-and-number-of-pages">

### Page number and number of pages

Headers and footers in Word document may contain dynamic fields like page number or total number of pages.  
Import from Word converter replaces those fields with HTML span elements with special class applied:

* Page number fields are replaced with `<span class="pageNumber"></span>`.
* Total number of pages fields are replaced with `<span class="totalPages"></span>`.

This assures compatibility with Export to Word Headers and Footers [page numbering and number of pages](#cs/latest/guides/export-to-word/headers-and-footers.html--page-number-and-number-of-pages) conversion.

An example Word document, and converted header:

```
<p>
    Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</p>

```

<a id="cs/latest/guides/import-from-word/headers-and-footers.html--known-limitations">

### Known limitations

* Headers and footers are not compatible with the comments and suggestions collaboration features.
* Due to lack of multi-section support, headers and footers are converted for first encoundered  
section with headers or footers defined.

<a id="cs/latest/guides/import-from-word/merge-fields.html">source file: "cs/latest/guides/import-from-word/merge-fields.html"</a>

## Merge fields

The converter provides support for the Word [Merge fields feature](https://support.microsoft.com/en-us/office/insert-mail-merge-fields-9a1ab5e3-2d7a-420d-8d7e-7cc26f26acff). Merge fields allow users to create templates, that can be later used to produce multiple documents using [mail merge](https://support.microsoft.com/en-gb/topic/how-to-use-the-mail-merge-feature-in-word-to-create-and-to-print-form-letters-that-use-the-data-from-an-excel-worksheet-d8709e29-c106-2348-7e38-13eecc338679).

Word Mail Merge allows you to effortlessly create personalized documents and streamline your communication process. You can generate tailored letters, emails, envelopes, labels, and directories by including specific details like names and addresses for each recipient.

With Word Mail Merge, you can automate the creation of customized documents, saving time and reducing manual effort. You can set up reusable templates to ensure consistency and speed in your communications.

This feature allows you to integrate data seamlessly from Excel spreadsheets, Access databases, Outlook contacts, and other sources directly into your Word documents, eliminating the need for manual data entry. It can help you reduce errors and maintain accuracy by using a single data source for all your documents, ensuring all personalized information is current and correct.

<a id="cs/latest/guides/import-from-word/merge-fields.html--converting-merge-fields">

### Converting merge fields

Merge fields are a feature of Word that is supported by Import from Word with full compatibility with the CKEditor 5 [Merge fields feature](#ckeditor5/latest/features/merge-fields.html).

To enable merge fields in Import From Word you need to provide their configuration via `config.merge_fields` option. ([Read about this configuration option in API documentation](https://docx-converter.cke-cs.com/v2/convert/docs#section/Import-from-Word/Configuration)).

Example of converting a Word document with merge fields:

```
{
    "config": {
        "merge_fields": {
            "prefix": "{",
            "suffix": "}"
        }
    }
}

```

```
<p>Hello {FirstName} {LastName}!</p>

```

The full list of the converted merge fields will be sent in the REST API payload:

```
{
    "html": "<p>Hello {FirstName} {LastName}!</p>",
    "merge_fields": [
        "FirstName",
        "LastName"
    ]
}

```

<a id="cs/latest/guides/import-from-word/multi-level-lists.html">source file: "cs/latest/guides/import-from-word/multi-level-lists.html"</a>

## Multi-level lists

Import from Word supports converting multi-level lists. These lists are a way to organize information using a hierarchy, where main points have subpoints beneath them. Each level contains a reference to its parent level to underline the connection between them. Multi-level lists make it easier to see the relationship between ideas and are often used in outlines or detailed reports.

<a id="cs/latest/guides/import-from-word/multi-level-lists.html--the-multi-level-lists-format">

### The multi-level lists format

Currently, Import from Word supports only legal lists. It is a special type of multi-level lists commonly used in legal documents to organize information systematically and clearly. They use Arabic numerals (1, 2, 3, etc.) exclusively to ensure consistency, readability, and ease of reference in contracts, statutes, or formal legal writing. Import from Word treats a list as a legal one only if the following conditions are met:

1. Each level uses the “decimal” numbering format (Arabic numerals – 1, 2, 3, etc.).
2. Each level has a numbering that references all previous levels. For example, level 3 must reference both level 1 and 2.
3. All list levels, including the skipped ones, must use the multi-level format of numbering (so the one referencing previous levels).

The following screenshot shows an example of a multi-level list in a Word document, listing American spacecrafts:

Upon importing it into the CKEditor–5, the following HTML is produced, compatible with the [multi-level lists feature](#ckeditor5/latest/features/lists/multi-level-lists.html) (some of the styling is removed to improve readability):

```
<h2>List of human spacecraft</h2>
<ol class="multi-level-list legal-list" style="list-style-type: none">
  <li>
    <h2>
      <span class="multi-level-list__marker">1. </span>American spacecraft
    </h2>
    <ol class="multi-level-list legal-list" style="list-style-type: none">
      <li>
        <h3><span class="multi-level-list__marker">1.1. </span>Manned</h3>
        <ol class="multi-level-list legal-list" style="list-style-type: none">
          <li>
            <p><span class="multi-level-list__marker">1.1.1. </span>Mercury</p>
          </li>
          <li>
            <p><span class="multi-level-list__marker">1.1.2. </span>Gemini</p>
          </li>
          <li>
            <p><span class="multi-level-list__marker">1.1.3. </span>Apollo</p>
          </li>
          <li>
            <p>
              <span class="multi-level-list__marker">1.1.4. </span>space shuttle
            </p>
            <ol
              class="multi-level-list legal-list"
              style="list-style-type: none"
            >
              <li>
                <p>
                  <span class="multi-level-list__marker">1.1.4.1. </span
                  >Columbia
                </p>
              </li>
              <li>
                <p>
                  <span class="multi-level-list__marker">1.1.4.2. </span
                  >Challenger
                </p>
              </li>
              <li>
                <p>
                  <span class="multi-level-list__marker">1.1.4.3. </span
                  >Discovery
                </p>
              </li>
              <li>
                <p>
                  <span class="multi-level-list__marker">1.1.4.4. </span
                  >Atlantis
                </p>
              </li>
              <li>
                <p>
                  <span class="multi-level-list__marker">1.1.4.5. </span
                  >Endeavour
                </p>
              </li>
            </ol>
          </li>
          <li>
            <p><span class="multi-level-list__marker">1.1.5. </span>Dragon</p>
          </li>
          <li>
            <p>
              <span class="multi-level-list__marker">1.1.6. </span>New Sheppard
            </p>
          </li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

```

The following screenshot shows how the list is rendered in CKEditor–5 thanks to the [multi-level lists feature](#ckeditor5/latest/features/lists/multi-level-lists.html):

<a id="cs/latest/guides/import-from-word/overview.html">source file: "cs/latest/guides/import-from-word/overview.html"</a>

## Import from Word - overview

CKEditor Cloud Services offer a fast and highly scalable service enabling the user to import the content from the Microsoft Word to HTML. The feature is available as a service, making it possible to send the Word file straight into the Cloud Services server or use it directly with [CKEditor 5 WYSIWYG editor plugin](#ckeditor5/latest/features/converters/import-word/import-word.html) that integrates the feature out of the box.

<a id="cs/latest/guides/import-from-word/overview.html--how-the-import-from-word-feature-works">

### How the Import from Word feature works

The DOCX to HTML converter provides a REST API for converting the Microsoft Word files to HTML documents. The service generates HTML data and returns it to the API consumer, allowing it to display it in the browser or inside a CKEditor 5 instance. It can be used to automate the conversion of Word files and allows for mass documents conversion with the omission of the editor.

Here you can see a simple document with some basic formatting in Word:

And here is the same sample document but already imported into CKEditor 5\. All the formatting was retained.

To integrate the feature into your environment, first check the [Quick start](#cs/latest/guides/import-from-word/quick-start.html) guide to start using it.

You can also test the feature using [the import from Word demo page](https://ckeditor.com/import-from-word/demo/#extended-import).

<a id="cs/latest/guides/import-from-word/overview.html--supported-file-types">

### Supported file types

The Import from Word feature supports the following file types:

* Microsoft Word `.docx`
* Microsoft Word template `.dotx`

If you would like to see other file types support introduced, please [contact us](https://ckeditor.com/contact/?sales=true#contact-form).

<a id="cs/latest/guides/import-from-word/overview.html--using-the-service-with-rest-api">

### Using the service with REST API

The REST API of the DOCX to HTML converter is an HTTP API service that allows you to convert Word files to HTML. Whether you just don’t use CKEditor 5 or want to migrate many Word documents from your database to HTML, you can use the API to integrate front-end or back-end applications with the Import from Word feature.

The service will preserve all formatting and styles from the Word document, including advanced features like collaboration features and document settings.

See the [Quick Start](#cs/latest/guides/import-from-word/quick-start.html) guide to learn more how to integrate REST API in your application.

<a id="cs/latest/guides/import-from-word/overview.html--the-import-from-word-editor-plugin">

### The Import from Word editor plugin

The [Import from Word CKEditor plugin](#ckeditor5/latest/features/converters/import-word/import-word.html) allows you to easily import Word files into your content, retaining formatting and rich media. When enabled, this feature takes care of the communication with the MS Word files converter, letting you enjoy Word documents in the editor.

Thanks to this plugin, all it takes is just one upload to keep on editing the content that was created in Word without interruption.

<a id="cs/latest/guides/import-from-word/overview.html--difference-between-paste-and-import">

#### Difference between Paste and Import

The CKEditor 5 WYSIWYG editor also offers a simpler [Paste from Office](#ckeditor5/latest/features/pasting/paste-from-office.html) plugin, which allows you to just paste content from Microsoft Word into your editor and maintain the original structure and formatting (provided the formatting features are supported by the editor setup).

See the [features comparison](#ckeditor5/latest/features/converters/import-word/features-comparison.html) guide to learn more about the differences between the Paste from Word and Import from Word features.

<a id="cs/latest/guides/import-from-word/overview.html--supported-features">

### Supported features

For a current list of all supported features that can be converted correctly by the Import from Word feature, please see the dedicated [supported features](#cs/latest/guides/import-from-word/content-formatting.html) guide.

<a id="cs/latest/guides/import-from-word/overview.html--stored-data">

### Stored data

The Import from Word converter is a service that generates an HTML document based on the `.docx` file provided by the customer. To perform the conversion, it requires the data to be sent from the Import from Word plugin or through the REST API, but the service itself is fully stateless.

The data (especially your sensitive data: the input file, converted HTML, comments, suggestions) is only used during the request processing and not stored. However, we do store some information needed for billing and maintaining our system. We try to reduce the amount of stored data to a required minimum and at this moment we store such information as the number and duration of imports, the final payload size, the number of unique imports, and statistical data (IP addresses, editor versions).

All logs related to processing requests are saved only in case of an unexpected situations and are stored for 14 days. The data in logs includes an error message, stack trace and information about the request.

<a id="cs/latest/guides/import-from-word/quick-start.html">source file: "cs/latest/guides/import-from-word/quick-start.html"</a>

## Import from Word - quick start

The aim of this article is to get you up and running with the Import from Word service.

Follow these steps:

* Subscribe to Import from Word on the [Premium Features Free Trial website](https://portal.ckeditor.com/checkout?plan=free).
* Generate your access credentials in the [Customer Portal](https://portal.ckeditor.com/).
* Configure CKEditor.

All the steps are explained in details below.

<a id="cs/latest/guides/import-from-word/quick-start.html--subscribe-to-ckeditor-cloud-services">

### Subscribe to CKEditor Cloud Services

Create an account in CKEditor Cloud Services by signing up to the Import from Word service. After signing up, you will receive access to the customer dashboard (Customer Portal).

<a id="cs/latest/guides/import-from-word/quick-start.html--log-in-to-the-customer-portal">

### Log in to the Customer Portal

Log into the [Customer Portal](https://portal.ckeditor.com) and navigate to “Your products > Cloud Services”.

From the list of available subscriptions in the dashboard, choose the Import from Word subscription that you want to manage and press the “Manage” link.

<a id="cs/latest/guides/import-from-word/quick-start.html--using-the-service-with-rest-api">

### Using the service with REST API

The Import from Word service may be used to convert Word files into the HTML data. In order to use it, authorization is needed in the form of an authorization token.

The authorization token needs to be passed as a value of the `Authorization` header.

```
{
     'Authorization': 'Your generated authorization token'
}

```

<a id="cs/latest/guides/import-from-word/quick-start.html--generating-the-authorization-token">

#### Generating the authorization token

The authorization token can be generated in two ways:

1. As a value returned from the [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html).
2. A locally created token.

<a id="cs/latest/guides/import-from-word/quick-start.html--creating-access-credentials">

#### Creating access credentials

From the list of environments, select the one that you want to manage (or create a new one).

Go to the “Access credentials” tab and click the “Create a new access key” button.

A modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

For your safety, the access key value will disappear in a few seconds. You will be able to display it again by clicking the “Show” button. Make sure to keep the access credentials in a safe place.

Read more about dealing with the credentials in the [Managing access credentials](#cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/import-from-word/quick-start.html--example-request">

#### Example request

Tokens for the Import from Word converter service require passing a payload with the `aud` parameter:

* `aud` – The environment ID.

The `accessKey` value needs to be replaced with your own access key generated before.

The following example presents a request that contains the required `Authorization` header for the converter:

```
const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );
const FormData = require( 'form-data' );

const accessKey = 'iGC6md5EcTG0DDZqEf4m4eytr679z0Ch2gIQuraBPzyWEtTbcpQAqAhA9LxpkDtpn';
const environmentId = 'DO3zekDU3LiJX8GOL2xt';

const token = jwt.sign( { aud: environmentId }, accessKey, { algorithm: 'HS256' } );

const formData = new FormData();

const config = {
    headers: {
        'Authorization': token,
        ...formData.getHeaders()
    }
};

const conversionConfig = {
    default_styles: true,
    collaboration_features: {
        user_id: 'example_user_id',
        comments: true,
        track_changes: false
    }
};

const file = fs.createReadStream( './file.docx' );

formData.append( 'config', JSON.stringify( conversionConfig ) );
// The file needs to be added as the last property to the form data.
formData.append( 'file', file, 'file.docx' );

axios.post( 'https://docx-converter.cke-cs.com/v2/convert/docx-html', formData, config )
    .then( response => {
        console.log( 'Conversion result', response.data );
    } )
    .catch( error => {
        console.log( 'Conversion error', error );
    } );


```

Please refer to the [converter documentation](https://docx-converter.cke-cs.com/docs) to start using the service.

<a id="cs/latest/guides/import-from-word/quick-start.html--using-the-import-from-word-feature-as-a-plugin">

### Using the Import from Word feature as a plugin

In order to use the [Import from Word feature](#ckeditor5/latest/features/converters/import-word/import-word.html) in your CKEditor 5 build, a token URL is needed for authorization.

<a id="cs/latest/guides/import-from-word/quick-start.html--creating-token-endpoint">

#### Creating token endpoint

Before you can use the feature, you first need to create a [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

<a id="cs/latest/guides/import-from-word/quick-start.html--development-token-endpoint-development-only">

##### Development token endpoint (development only)

If you are just starting, you may use the development token endpoint URL, which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in these three simple steps:

1. To work with CKEditor premium features like real-time collaboration, exports or import, you need to create an environment. Environments allow you to create access credentials, manage webhooks, configure features and connect to CKEditor Cloud Services. You may have more than one to serve separate instances or integrations. From the list of the environments, choose the one that you want to manage or create one.
1. The development token URL will show up in the “Development token URL” section:

<a id="cs/latest/guides/import-from-word/quick-start.html--writing-your-own-token-endpoint-production">

##### Writing your own token endpoint (production)

To write your own [security token endpoint](#cs/latest/developer-resources/security/token-endpoint.html), you need to create access credentials for the selected environment by going to the “Access credentials” tab and clicking the “Create a new access key” button.

Read more in the [Creating access credentials](#cs/latest/developer-resources/security/access-key.html--creating-access-credentials) section of the Environments management guide.

<a id="cs/latest/guides/import-from-word/quick-start.html--integrating-the-import-from-word-plugin-with-the-application">

#### Integrating the Import from Word plugin with the application

To install the plugin into your WYSIWYG editor, use the [online builder](https://ckeditor.com/ckeditor-5/online-builder/) to generate a custom CKEditor 5 build with the plugin enabled. Alternatively, refer to the [installation guide](#ckeditor5/latest/features/converters/import-word/import-word.html--installation) in the plugin documentation to do it on your own.

Configure the plugin using the token generated earlier, pasting the link in the configuration (see [CloudServicesConfig](https://ckeditor.com/docs/ckeditor5/latest/api/module%5Fcloud-services%5Fcloudservicesconfig-CloudServicesConfig.html)):

```
    ClassicEditor
        .create( document.querySelector( '#editor' ), {
            importWord: {
                tokenUrl: 'https://example.com/cs-token-endpoint',
            }
        } )
        .then( ... )
        .catch( ... );

```

This is all. At this point, the Import from Word feature will be automatically enabled in your application.

Refer to the [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html) guide if you need more information on integrating Import from Word with your WYSIWYG editor!

<a id="cs/latest/guides/import-from-word/sections.html">source file: "cs/latest/guides/import-from-word/sections.html"</a>

## Sections

<a id="cs/latest/guides/import-from-word/sections.html--document-properties">

### Document properties

The converter recognizes the default Word section and outputs information about document size, document margins and document language. Dimensions of document size and margins are returned in pixels:

```
{
  "html": "<p>Hello, World!</p>",
  "document_size": {
    "width": 793.73,
    "height": 1122.53
  },
  "document_margins": {
    "top": 96,
    "right": 96,
    "bottom": 48,
    "left": 48
  },
  "document_language": "en-US"
}

```

The section settings like margins and document size are converted from the final section of the `.docx` file. It means, if there were multiple settings e.g. for margins, these will not make it into the effecting converted content.

<a id="cs/latest/guides/import-from-word/sections.html--known-limitations">

#### Known limitations

* As for now, the converter does not support multiple sections in the `.docx` file. It means that if there are multiple sections in the `.docx` file, only the last section will be converted.
* Multi-column sections layout is not supported.

<a id="cs/latest/guides/import-from-word/styles.html">source file: "cs/latest/guides/import-from-word/styles.html"</a>

## Overview

There are several ways to apply content formatting in Word. The first one is inline styling that is applied via various toolbar buttons and dropdowns. This formatting happens “in place”, and it always takes precedence over any other types of formatting.

The more advanced way to format large portions of a document are styles. This kind of formatting is applied to specific areas, like titles, headers, regular paragraphs, lists etc. and it is global, i.e. it is applied to the whole Word document.

The last way to style the document content are default document properties. They are applied via Format options, similarly to some inline styles, with the exception of choosing an option to apply them as the default formatting instead of the inline one.

The Import from Word converter recognizes all these styling methods and applies them by converting all of them into valid inline HTML styling.

<a id="cs/latest/guides/import-from-word/styles.html--content-formatting">

### Content formatting

For a current list of all supported features that can be converted correctly by the Import from Word feature, please see [dedicated guide](#cs/latest/guides/import-from-word/content-formatting.html).

<a id="cs/latest/guides/import-from-word/styles.html--word-styles">

### Word styles

Styles in Word documents allow keeping your formatting consistent within a document. Instead of applying the bold style to each heading, you can create a style that will include all required formatting and can be reused multiple times. This way, if you need to change the formatting, you only need to change it in the style, and it will be applied to all paragraphs that use that style.

For example, in the following document we applied a couple of different styles that provide the semantic value to the document and keep it clean and consistent:

The Import from Word converter recognizes all these styles and applies them to HTML, ensuring that the document is styled in the same way as in the original Word document. The applied styles follow the same formatting rules as [content formatting](#cs/latest/guides/import-from-word/content-formatting.html).

Styles can be freely modified by the user and Import from Word ensures that they are converted properly, giving you a powerful tool to keep the proper document formatting inside your application.

The conversion of Word styles can also be disabled using the `formatting.styles` configuration option:

```
const config = {
    formatting: {
        styles: 'none'
    }
}

```

Setting the `formatting.styles` configuration option to `'none'` will result in a document that does not include any Word styles.

<a id="cs/latest/guides/import-from-word/styles.html--supported-features">

#### Supported features

* Built-in Word styles, including custom modifications applied to them.
* User-made styles that use different fonts, paragraphs, borders and numbering formatting.
* Full support of “toggle properties”, i.e. character formatting properties, such as the bold formatting, that are toggled according to their positions in the style hierarchy.

<a id="cs/latest/guides/import-from-word/styles.html--known-limitations">

### Known limitations

* List styles are not supported.
* Circular style references are not supported.

<a id="cs/latest/guides/import-from-word/styles.html--default-styles">

### Default styles

Word allows changing the default formatting of documents to style it in a specific way. You can apply the same style to the whole Word document without the need to apply it manually. For example, you can open the Format menu, choose the Font option and then change some formatting such as font size and font family. After that, choose the “Default…” option and confirm the second dialog:

The behavior of that Word feature highly impacts how the document will be styled after the conversion. Therefore, instead of always applying the default styles, this behavior is configurable via the `formatting.defaults` configuration option:

```
const config = {
    formatting: {
        defaults: 'inline'
    }
}

```

This option is disabled by default, which means that the document conversion will only keep styles explicitly applied by the user. Setting the `formatting.defaults` configuration option to `'inline'`, will result in applying all styles that are used in a document.

<a id="cs/latest/guides/import-from-word/styles.html--supported-features-2">

#### Supported features

* Format, font and paragraph default styles that are applied to the whole document.
* Line height and spacing default styles, that are not explicitly set by a user, but can be inferred from the Word specification.
* Fonts declared in the document theme.

<a id="cs/latest/guides/import-from-word/styles.html--css-resets">

### CSS resets

Browsers provide their own CSS stylesheets that apply default formatting to common HTML elements. That formatting is not always compatible with the default Word formatting. The example of such a discrepancy could be headings: in Word they are not bold by default but in HTML they are. The Import from Word feature could remove such differences thanks to the `formatting.resets` configuration option:

```
const config = {
    formatting: {
        resets: 'inline'
    }
}

```

Setting this option to `'inline'` will include all resetting styles in the HTML result, e.g. headings will have their font weight reset:

```
<h1 style="font-weight: normal">Heading 1</h1>

```

<a id="cs/latest/guides/import-from-word/styles.html--supported-features-3">

#### Supported features

* Reset of font weight and font size of HTML headings.
* Removal of additional margins around HTML lists.
* Removal of additional margins around HTML tables.
* Reset of font weight and text alignment of HTML table cell headings.
* Reset of underlines drawn when they pass over glyph ascenders and descenders.

<a id="cs/latest/guides/index.html">source file: "cs/latest/guides/index.html"</a>

## CKEditor Cloud Services

The CKEditor Cloud Services is a cloud platform for editing and real-time collaboration services. It serves as a supporting backend for selected rich text editing features available in CKEditor 5 and CKEditor 4.

Refer to the following sections for more information:

* [CKEditor Cloud Services - Introduction](#cs/latest/guides/overview.html) – An introduction to the CKEditor Cloud Services.
* [Collaboration - Quick start](#cs/latest/guides/collaboration/quick-start.html) – Learn how to set up the Collaboration and connect it with CKEditor 5.
* [Export to PDF - Quick Start](#cs/latest/guides/export-to-pdf/quick-start.html) – Learn how to set up the PDF Converter service and connect it with CKEditor.
* [Export to Word - Quick Start](#cs/latest/guides/export-to-word/quick-start.html) – Learn how to set up the HTML to DOCX Converter service and connect it with CKEditor.
* [Import from Word - Quick Start](#cs/latest/guides/import-from-word/quick-start.html) – Learn how to set up the DOCX to HTML Converter service and connect it with CKEditor.

<a id="cs/latest/guides/overview.html">source file: "cs/latest/guides/overview.html"</a>

## Introduction to CKEditor Cloud Services

The CKEditor Cloud Services is a cloud platform that provides editing and real-time collaboration services. The platform comprises of several services, each of which can connect to CKEditor 5 using dedicated plugins. Additionally, each service has a REST API for synchronizing the data, utilizing, configuring, and managing features.

The platform primarily focuses on providing a backend for the CKEditor 5 features, although some features can also be used directly through REST APIs.

The following diagram illustrates the components of CKEditor Cloud Services, as well as the different parts of the ecosystem and external components with which it integrates.

<a id="cs/latest/guides/overview.html--real-time-collaboration">

### Real-time collaboration

CKEditor Cloud Services offers a fast and highly scalable service for real-time collaboration, compatible with rich text editors built on top of CKEditor 5 Framework. It is capable of handling real-time collaboration on text documents and tracking users connected to the document. It also serves as a storage for comments, suggestions, and revisions added to the document.

Apart from having a supporting backend to transmit operations, resolve conflicts, and apply changes between users connected to the same document, some features are needed on the client side to offer a full real-time collaboration experience:

* Showing multiple cursors and selections coming from other users.
* Showing users connecting to and disconnecting from the document.
* Offering the UI for managing comments and markers in the document.

The CKEditor Ecosystem offers a collection of plugins that can be integrated with any CKEditor 5 build to provide a fully flexible and customizable experience – the [CKEditor 5 Collaboration Features](https://ckeditor.com/collaboration/).

<a id="cs/latest/guides/overview.html--ckeditor-5-real-time-collaboration-features">

#### CKEditor 5 Real-time collaboration features

[CKEditor 5 Real-time collaboration features](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) let you customize any CKEditor 5 build to include real-time collaborative editing, commenting, and track changes features and tailor them to your needs.

Real-time collaboration consists of four features delivered as separate plugins that can be used with any CKEditor 5 build:

* [Real-time collaborative editing](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) – Allows for editing the same document by multiple users simultaneously. It also automatically solves all conflicts if users make changes at the same time.
* [Real-time collaborative comments](#ckeditor5/latest/features/collaboration/comments/comments.html) – Makes it possible to add comments to any part of the content in the editor.
* [Real-time collaborative track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html) – Changes to the content are saved as suggestions that can be accepted or discarded later.
* [Real-time collaborative revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html) – Multiple versions of the document are available, an older version can be restored.
* [Users selection and presence list](#ckeditor5/latest/features/collaboration/real-time-collaboration/users-in-real-time-collaboration.html) – Shows the selection of other users and lets you view the list of users currently editing the content in the editor.

All of the above features are customizable. This makes implementing real-time collaborative editing within your application a highly customizable out-of-the-box experience.

<a id="cs/latest/guides/overview.html--server-side-editor-api">

#### Server-side Editor API

The [Server-side Editor API](#cs/latest/guides/collaboration/server-side-editor-api.html) enables deep and complex integration of your application with all document data, allowing you to manipulate content and manage collaborative data such as suggestions, comments, and revision history directly from your server-side code.

The remote script REST API endpoint allows you to execute any JavaScript code that uses the CKEditor 5 API, that could be executed by a browser, but without a need to open the editor by a human user. Instead, the script is executed on the Cloud Services server allowing for updating and interacting with active collaboration sessions remotely.

This feature is particularly useful for:

* **Automation**: Run content processing tasks as part of your backend workflows.
* **Scalability**: Process multiple documents simultaneously without client-side limitations.
* **Security**: Process sensitive content in a controlled environment without exposing it to client-side manipulation.
* **Integration**: Connect with other server-side systems and databases directly.

For an in-depth introduction to CKEditor 5 Collaboration Features refer to the [Collaboration overview](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html).

<a id="cs/latest/guides/overview.html--export-features">

### Export features

CKEditor Cloud Services offers a fast and highly scalable service enabling the user to export documents either to a Microsoft Word document or to a PDF document. Both of these are available as a service, making it possible to feed the data straight into the Cloud Services server for more advanced use or as convenient WYSIWYG editor plugins for ease of use in less demanding cases.

<a id="cs/latest/guides/overview.html--export-to-pdf">

#### Export to PDF

The [Export to PDF](#cs/latest/guides/export-to-pdf/overview.html) converter provides an API for converting HTML documents to PDF files. The service generates a file and returns it to the user so they can save it in the `.pdf` format on their disk. This allows you to easily turn your content into the storable final PDF format file collection. Available both as a service endpoint (a premium feature) and as a plugin (needs to be added to the editor build separately).

<a id="cs/latest/guides/overview.html--export-to-word">

#### Export to Word

The [Export to Word](#cs/latest/guides/export-to-word/overview.html) converter provides an API for converting HTML documents to Microsoft Word `.docx` files. The service generates a Word file and returns it to the user so they can save it in the `.docx` format on their disk. This allows you to easily export your content to the Microsoft Word format. Available both as a service endpoint (a premium feature) and as a plugin (needs to be added to the editor build separately).

<a id="cs/latest/guides/overview.html--import-from-word">

### Import from Word

The [Import from Word](#cs/latest/guides/import-from-word/overview.html) converter is a fast and highly scalable service enabling the user to import documents from a Microsoft Word `.docx` file. The feature is available as a service, making it possible to send a `.docx` file straight into the Cloud Services server for more advanced use or as a convenient [CKEditor 5 WYSIWYG editor plugin](#ckeditor5/latest/features/converters/import-word/import-word.html) for the ease of use in less demanding cases.

The DOCX to HTML converter provides an API for converting Microsoft Word `.docx` files to HTML documents. The service generates HTML data and returns it to the user so they can save it in the HTML format on their disk.

<a id="cs/latest/guides/overview.html--ckbox">

### CKBox

The [CKBox](https://ckeditor.com/ckbox/) is a service that manages document assets and images. It allows for seamless uploading and management of assets within a document. The service stores them in persistent storage and provides tools to optimize image size and manage attributes, such as alternative text. Once an asset is stored, it can be reused in multiple documents.

Refer to the [documentation](#ckbox/latest/guides/index.html) for details.

<a id="cs/latest/guides/overview.html--cloud-region-and-on-premises-options">

### Cloud region and on-premises options

Cloud Services are available both as a cloud solution (SaaS) and as a self-hosted (on-premises) version. You can learn more about the different approaches in the dedicated [SaaS vs. On-premises](#cs/latest/guides/saas-vs-on-premises.html) guide.

The cloud solution offers two regions to host your services. You can choose the [EU, US, or both cloud regions](#cs/latest/guides/saas-vs-on-premises.html--cloud-region) when working with a cloud-hosted SaaS setup.

<a id="cs/latest/guides/overview.html--next-steps">

### Next steps

* If you are interested in CKEditor 5 collaboration features, check the [Collaboration overview](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html) guide for information on how to enable real-time collaborative editing in your CKEditor 5 build.
* If you already use collaboration features without Real-time Collaboration you can refer to our dedicated guide about [migration of data between non-RTC and RTC editors](#cs/latest/guides/collaboration/migrating-to-rtc.html)
* If you need to save your documents in portable file formats, check out the [Export to PDF](#cs/latest/guides/export-to-pdf/overview.html) or [Export to Word](#cs/latest/guides/export-to-word/overview.html) feature guides.
* If you need to import your documents from the `.docx` format, learn more about the [Import from Word](#cs/latest/guides/import-from-word/overview.html) feature.
* If you are interested in the CKBox asset manager, check the [CKBox quick start](#ckbox/latest/guides/quick-start.html) guide for a short instruction on how to start using CKBox.

<a id="cs/latest/guides/saas-vs-on-premises.html">source file: "cs/latest/guides/saas-vs-on-premises.html"</a>

## SaaS vs. On-Premises

CKEditor Cloud Services is available in two variants.

The first one is **Software as a Service (SaaS)**. In this variant, CKSource takes care of all the needed infrastructure, adjusts the servers to the current needs, ensures data safety as well as performs and restores backups in case of any losses. After completing the purchase, the customer can log into the Customer Portal where they can find all the credentials needed to get up and running with CKEditor Cloud Services. The SaaS environment runs on the AWS infrastructure, which allows us to keep the availability on a high level. You can read more about server security on the [security page](#cs/latest/guides/system-security.html).

The other approach is **On-Premises**, where CKSource only provides the software. It is the customer that is responsible for the installation, the provision and maintenance of the servers. In addition, the customer needs to monitor the servers, scale the application in response to the increased usage, as well as take care of creating and restoring backups. Before running CKEditor Cloud Services for the first time, the customer needs to prepare the whole environment, which requires additional work by developers.

<a id="cs/latest/guides/saas-vs-on-premises.html--updates">

### Updates

New features and fixes are applied to SaaS immediately after being tested, while the On-Premises Docker images are released periodically every 6 weeks and the On-Premises installation has to be updated manually.

<a id="cs/latest/guides/saas-vs-on-premises.html--support-and-monitoring">

### Support and monitoring

Whatever the chosen CKEditor Cloud Services variant, CKSource customers are always provided with top-quality assistance. Thanks to the robust monitoring system, the CKSource team is able to swiftly debug SaaS application problems. Support for On-Premises is also provided but, due to the infrastructure being managed on the customer’s end, it requires closer cooperation between CKSource and the client’s team.

To read more about how the CKEditor Team monitors the application, check out the [security notes](#cs/latest/guides/system-security.html--security-monitoring-and-incident-response).

<a id="cs/latest/guides/saas-vs-on-premises.html--cloud-region">

### Cloud region

To host your Cloud Services applications, you can **choose between the EU and US cloud regions**. If you need broader coverage, Multi-region support (available in the Custom plan) lets you create and manage environments in both regions as needed. Serving users from the region closest to them helps optimize editor performance within your application, reducing latency and improving responsiveness.

The chosen region also determines **data residency**, which is especially important for **GDPR compliance** and for organizations operating in highly regulated industries. For more details, refer to the [“Cloud regions and data residency”](#cs/latest/guides/system-security.html--cloud-regions-and-data-residency) section of the [Security and privacy](#cs/latest/guides/system-security.html) guide.

<a id="cs/latest/guides/saas-vs-on-premises.html--next-steps">

### Next steps

* Check the CKEditor Cloud Services [On-premises documentation](#cs/latest/onpremises/index.html).
* Check the [Quick Start](#cs/latest/guides/collaboration/quick-start.html) guide and try out CKEditor 5 with collaboration.

<a id="cs/latest/guides/status-page.html">source file: "cs/latest/guides/status-page.html"</a>

## Cloud Services status page

We keep the [Cloud Services status page](https://status.ckeditor.com/) accessible for everyone. You can check the current status of our services there, as well as the uptime and details about planned maintenances or previous incidents. You can also subscribe to be notified whenever CKEditor Cloud Services creates, updates, or resolves an incident.

Visit the [Cloud Services status page](https://status.ckeditor.com/).

<a id="cs/latest/guides/system-security.html">source file: "cs/latest/guides/system-security.html"</a>

## Security and Privacy Overview

At CKEditor, we care deeply about security and privacy. Our Cloud Services are built on a strong, flexible system that protects your data with advanced security measures and constant monitoring. We are certified to SOC 2 Type 2 standards, which means we follow the industry’s best practices to keep your data secure, available, and private. We also believe in being open and honest, so we keep you informed about our operations.

<a id="cs/latest/guides/system-security.html--infrastructure-and-hosting-on-aws">

### Infrastructure and Hosting on AWS

CKEditor Cloud Services uses Amazon Web Services (AWS) for hosting. AWS is a well-known and trusted cloud platform that offers strong security, the ability to grow efficiently, and the ability to follow important rules. By choosing AWS, we ensure our services run on a safe and strong system. This helps us provide our users with the best performance, reliability, and data protection.

<a id="cs/latest/guides/system-security.html--global-infrastructure">

#### Global Infrastructure

We operate within the **US East (Northern Virginia)** and **European (Frankfurt)** AWS regions. The [users residency and local legal solutions](#cs/latest/guides/system-security.html--cloud-regions-and-data-residency) can affect the choice between these two.

We use AWS to provide services, such as:

* **AWS ECS** to manage containerized applications. ECS provides a highly scalable and reliable way to orchestrate workloads, ensuring automatic scaling and distribution of resources to handle traffic spikes.
* **AWS ALB** to efficiently distribute traffic. This helps maintain performance and availability, even if some instances experience heavy load or failure.
* **AWS RDS** – an engine for databases that provide automated backups, multi-AZ replication, and point-in-time recovery.
* **AWS Elasticache** to cache in-memory to ensure faster response times for our users.
* **AWS SNS/SQS** for reliable message queuing, enabling asynchronous communication in the system.

<a id="cs/latest/guides/system-security.html--aws-security-services">

#### AWS Security Services

AWS provides a wide range of built-in security services that enhance our platform’s protection:

* **AWS GuardDuty** actively protects our system. It always watches for suspicious or unauthorized activity in our AWS environment, helping us quickly spot and respond to any possible security threats.
* **AWS Security Hub** is a centralized security monitoring and compliance check across the entire AWS infrastructure.
* **AWS AppConfig** manages dynamic configuration changes across applications, allowing us to safely and quickly deploy configuration updates without impacting the system’s security or stability.
* **AWS Config** continuously monitors and assesses the configuration of our AWS resources to ensure compliance with internal security policies and best practices. AWS Config helps us track configuration changes and identify resources that may be non-compliant.
* **AWS CloudTrail** records and logs all API activity and changes across our AWS infrastructure, providing complete visibility into user actions for auditing and incident response purposes. CloudTrail ensures a comprehensive audit trail of every action taken on our resources.
* **AWS Certificate Manager (ACM)** automatically manages and provisions **SSL/TLS certificates** to secure our application traffic. This ensures all communication is encrypted, providing secure connections between the user and our services.
* **AWS Secrets Manager** protects sensitive data, such as all configurations and database credentials, by securely storing and managing access to secrets.
* **AWS Key Management Service (KMS)** handles cryptographic keys for encrypting data, ensuring strict control and compliance with industry standards.
* **AWS CloudWatch** collects and monitors real-time logs, performance metrics, and application data to detect security and operational anomalies.

<a id="cs/latest/guides/system-security.html--aws-compliance">

#### AWS Compliance

AWS complies with a wide range of global security and compliance certifications, including **SOC 1**, **SOC 2**, **SOC 3**, **ISO 27001**, **ISO 27017**, **ISO 27018**, and **GDPR**. CKEditor Cloud Services benefits from these certifications, inheriting the strong security posture of the AWS cloud.

<a id="cs/latest/guides/system-security.html--virtual-private-cloud-vpc">

#### Virtual Private Cloud (VPC)

All components of CKEditor Cloud Services are hosted on an **AWS VPC**, which provides network isolation. Public access is limited to load balancers, and all other components are protected behind strict security controls such as **Security Groups,** **Network Access Control,** and **VPN access**.

<a id="cs/latest/guides/system-security.html--security-groups">

#### Security Groups

To control the traffic allowed into and out of our instances, we rely on AWS **Security Groups**. These groups are configured with strict and restrictive firewall rules, ensuring only authorized traffic can interact with our systems. This approach significantly enhances the security of our platform. Network access control lists provide an additional security layer operating on subnets/networking level.

<a id="cs/latest/guides/system-security.html--web-application-firewall-waf">

#### Web Application Firewall (WAF)

We use **AWS WAF** to protect our system from common web attacks. This includes things like **SQL injection** and **cross-site scripting (XSS)**. The WAF constantly updates its protection rules to defend against new threats.

<a id="cs/latest/guides/system-security.html--ddos-protection">

#### DDoS Protection

To defend against **Distributed Denial of Service (DDoS)** attacks, we use **AWS Shield Advanced.** This managed DDoS protection service protects our web applications at network and application levels. **AWS CloudFront** and **Route 53** also provide additional layers of DDoS mitigation by distributing traffic and reducing the attack surface.

<a id="cs/latest/guides/system-security.html--high-availability-and-disaster-recovery">

### High Availability and Disaster Recovery

Ensuring **high availability** and **resilience** is fundamental to CKEditor Cloud Services.

<a id="cs/latest/guides/system-security.html--multi-zone-redundancy">

#### Multi-Zone Redundancy

Our services are deployed across multiple **AWS availability zones.** This means if one location has problems, we can quickly switch to another. This keeps our service running smoothly without interruptions.

<a id="cs/latest/guides/system-security.html--data-replication">

#### Data Replication

Databases are continuously **replicated** across multiple availability zones, providing redundancy and fault tolerance. When an availability zone becomes unavailable, the system automatically switches to another.

<a id="cs/latest/guides/system-security.html--data-backup-and-recovery">

#### Data Backup and Recovery

CKEditor Cloud Services automatically backs customer data with **point-in-time recovery** capabilities for up to 7 days. Backups are securely encrypted and stored in multiple AWS locations, ensuring the highest levels of redundancy and data protection.

<a id="cs/latest/guides/system-security.html--disaster-recovery-plan">

#### Disaster Recovery Plan

We have a thorough plan to quickly get our systems back up and running if something goes wrong. We regularly test this plan to make sure it works well. This helps us keep our services available despite a big problem.

<a id="cs/latest/guides/system-security.html--9999-uptime-sla">

#### 99.99% Uptime SLA

Our infrastructure is designed to deliver a **99.99% uptime SLA**, supported by AWS’s highly reliable services.

<a id="cs/latest/guides/system-security.html--data-security-and-encryption">

### Data Security and Encryption

Data security is at the heart of CKEditor Cloud Services, and we implement strong encryption and access control measures to protect sensitive information.

<a id="cs/latest/guides/system-security.html--encryption-at-rest-and-in-transit">

#### Encryption at Rest and in Transit

All data is encrypted using **AES-256** at rest, and **TLS 1.2+** encryption is enforced for all communications in transit. This ensures that data is securely transmitted and stored without exposure to unauthorized access.

<a id="cs/latest/guides/system-security.html--data-isolation">

#### Data Isolation

We isolate customer data using **separate encryption keys** for each customer and environment. This ensures that customer data is fully segregated and protected from unauthorized access.

<a id="cs/latest/guides/system-security.html--key-management">

#### Key Management

Our encryption keys are managed using **AWS Key Management Service (KMS)**, which ensures that all cryptographic operations meet the highest security standards.

<a id="cs/latest/guides/system-security.html--access-control-and-identity-management">

### Access Control and Identity Management

Access control is tightly enforced across CKEditor Cloud Services, ensuring only authorized personnel can access critical systems and data.

<a id="cs/latest/guides/system-security.html--role-based-access-control-rbac">

#### Role-Based Access Control (RBAC)

Permissions are assigned based on roles, ensuring that users have access only to the data and systems necessary for their job functions. Regular access reviews ensure that permissions remain appropriate over time.

<a id="cs/latest/guides/system-security.html--multi-factor-authentication-mfa">

#### Multi-Factor Authentication (MFA)

We enforce **MFA** for all privileged access to the CKEditor Cloud Services infrastructure. This additional layer of protection ensures that even if credentials are compromised, unauthorized access is prevented.

<a id="cs/latest/guides/system-security.html--single-sign-on-sso">

#### Single Sign-On (SSO)

Internal access to systems is centralized using **Google SSO**, minimizing password management risks and improving security.

<a id="cs/latest/guides/system-security.html--access-audits">

#### Access Audits

We perform regular access audits, logging all access attempts and monitoring for any suspicious activity. All changes to access rights are logged and can be audited for compliance and security purposes.

<a id="cs/latest/guides/system-security.html--application-and-code-security">

### Application and Code Security

At CKEditor, we follow a secure **Software Development Life Cycle (SDLC)**, ensuring security is embedded in every stage of development.

<a id="cs/latest/guides/system-security.html--code-reviews">

#### Code Reviews

All changes to our code are carefully checked by engineers. This helps catch any potential security problems before they can affect our live system. We do this to make sure our code is safe and works well.

<a id="cs/latest/guides/system-security.html--automated-code-analysis">

#### Automated Code Analysis

We use **static code analysis tools** to scan code for vulnerabilities and insecure practices automatically. These scans ensure that every line of code adheres to security standards (for example **OWASP Top Ten**).

<a id="cs/latest/guides/system-security.html--automated-testing">

#### Automated Testing

All code is subject to **automated unit testing** and **integration testing** to validate its functionality and security.

<a id="cs/latest/guides/system-security.html--quality-assurance-qa-testing">

#### Quality Assurance (QA) Testing

Our QA team conducts **manual** and **automated testing on all updates before being deployed** to production. This includes security testing, performance testing, and functional validation to ensure the application’s integrity and security.

<a id="cs/latest/guides/system-security.html--continuous-integrationcontinuous-deployment-cicd">

#### Continuous Integration/Continuous Deployment (CI/CD)

Our CI/CD pipeline ensures that all deployments to production are automated and pass through multiple layers of security checks. Only code that meets strict security and performance criteria is allowed to be deployed.

<a id="cs/latest/guides/system-security.html--vulnerability-management-and-patch-updates">

### Vulnerability Management and Patch Updates

We take a proactive approach to identifying and mitigating vulnerabilities across our systems.

<a id="cs/latest/guides/system-security.html--continuous-vulnerability-scanning">

#### Continuous Vulnerability Scanning

We use automated tools to scan our infrastructure and applications for known vulnerabilities continuously. These scans reference the latest **Common Vulnerabilities and Exposures (CVE)** database.

<a id="cs/latest/guides/system-security.html--penetration-testing">

#### Penetration Testing

We engage third-party security experts to perform annual **penetration testing** of our systems, identifying potential vulnerabilities and ensuring our security posture remains robust.

<a id="cs/latest/guides/system-security.html--timely-patch-management">

#### Timely Patch Management

Our **patch management policy** ensures that security patches are applied promptly to mitigate potential risks. Critical patches are prioritized for immediate deployment, while non-critical updates are tested before implementation.

<a id="cs/latest/guides/system-security.html--security-monitoring-and-incident-response">

### Security Monitoring and Incident Response

We continuously monitor our environment for security and performance, ensuring that any issues are swiftly identified and resolved.

<a id="cs/latest/guides/system-security.html--real-time-monitoring">

#### Real-Time Monitoring

Using **AWS CloudWatch**, **AWS GuardDuty**, **AWS Security Hub** we continuously monitor for security events, performance metrics, and operational anomalies. If suspicious activity is detected, automated alerts are generated for immediate investigation.

<a id="cs/latest/guides/system-security.html--automated-alerts">

#### Automated Alerts

Any abnormal activity, such as unauthorized access attempts or unusual traffic patterns, triggers real-time alerts. Our team reviews these alerts to prevent potential incidents.

<a id="cs/latest/guides/system-security.html--incident-response-plan">

#### Incident Response Plan

CKEditor Cloud Services has a clear plan for handling all security and reliability problems. This plan explains how we find, investigate, and fix issues. After each incident, we do a post-mortem analysis and review to determine why it occurred and improve our system to prevent similar incidents in the future.

<a id="cs/latest/guides/system-security.html--audit-logs">

#### Audit Logs

We maintain detailed **audit logs** of all actions taken in production environments, ensuring transparency and accountability. Logs are securely stored and available for review during security investigations or audits.

<a id="cs/latest/guides/system-security.html--observability-and-continuous-testing">

### Observability and Continuous Testing

To ensure **high availability** and a seamless user experience, CKEditor Cloud Services continuously tests and monitors its applications through **real-user simulations**.

<a id="cs/latest/guides/system-security.html--performance-monitoring">

#### Performance Monitoring

We monitor key performance indicators (KPIs) such as **network usage**, **CPU and memory utilization**, **latency** **request processing time, and more**. All metrics are stored in **Prometheus** and **Grafana.** Any deviation from expected performance levels triggers alerts and investigations by our operations team.

<a id="cs/latest/guides/system-security.html--tests-bots">

#### Tests Bots

We employ **automated bots** that simulate fundamental user interactions with the system regularly (every 10 minutes), continuously testing for performance, reliability, and potential issues. These bots help identify potential bottlenecks or problems before they impact customers.

<a id="cs/latest/guides/system-security.html--soc-2-type-2-certification">

### SOC 2 Type 2 Certification

As of January 2025, CKEditor Cloud Services is **SOC 2 Type 2** certified, demonstrating our adherence to the highest **security**, **availability**, and **confidentiality standards**.

<a id="cs/latest/guides/system-security.html--security-controls">

#### Security Controls

Our SOC 2 certification confirms that we have implemented robust security controls to protect customer data from unauthorized access, ensuring compliance with best industry practices.

<a id="cs/latest/guides/system-security.html--global-privacy-compliance">

#### Global Privacy Compliance

We comply with key global privacy regulations, including **GDPR**, ensuring your data is handled with the utmost care and transparency.

<a id="cs/latest/guides/system-security.html--vendor-and-subprocessor-management">

### Vendor and Subprocessor Management

CKEditor Cloud Services partners with trusted vendors to deliver reliable and secure services. We ensure all subprocessors comply with strict security and privacy requirements.

<a id="cs/latest/guides/system-security.html--amazon-web-services-aws">

#### Amazon Web Services (AWS)

Our primary hosting provider is **AWS**, compliant with **SOC 1**, **SOC 2**, **ISO 27001**, and **GDPR**. AWS’s infrastructure provides a secure foundation for CKEditor Cloud Services, ensuring high availability and data security.

<a id="cs/latest/guides/system-security.html--annual-subprocessor-reviews">

#### Annual Subprocessor Reviews

We perform **annual reviews** of all subprocessors to ensure they maintain compliance with industry standards and regulatory requirements, including SOC 2 and GDPR.

<a id="cs/latest/guides/system-security.html--cloud-regions-and-data-residency">

### Cloud Regions and Data Residency

We operate within the **US East (Northern Virginia)** and **European (Frankfurt)** AWS regions.

The choice of a cloud region determines **data residency** and can help meet the legal requirements (such as **GDPR compliance**) and performance KPIs (by locating the services closer to your end users).

The table below offers a more detailed insight into differences between both locations and their effects on each Cloud Services service.

| Service                          | Purpose of Processing                                                    | Stores Data | Data at Rest [\[3\]](#cs/latest/guides/system-security.html--legend-3)                                                                                                                                                                         | Data in Transit [\[2\]](#cs/latest/guides/system-security.html--legend-2)  | Storage & Processing Location                                                                         | Notes                                                                                                                                                                                                                                                                          |
| -------------------------------- | ------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Real-time Collaboration**      | Enable multi-user editing                                                | Yes         | User data (ID, email, name, avatar URL) Comments and suggestion threads Document content [\[1\]](#cs/latest/guides/system-security.html--legend-1) All the data is encrypted at rest [\[4\]](#cs/latest/guides/system-security.html--legend-4) | Same as at rest                                                            | Selected cloud region [\[0\]](#cs/latest/guides/system-security.html--legend-0)                       | —                                                                                                                                                                                                                                                                              |
| **Document Conversion**          | Format conversion                                                        | No          | —                                                                                                                                                                                                                                              | Provided DOCX/HTML                                                         | Selected cloud region [\[0\]](#cs/latest/guides/system-security.html--legend-0)                       | —                                                                                                                                                                                                                                                                              |
| **CKBox**                        | Store and serve files                                                    | Yes         | Uploaded files and their metadata                                                                                                                                                                                                              | Same as at rest                                                            | Selected cloud region [\[0\]](#cs/latest/guides/system-security.html--legend-0) ⚠️ See "Notes"        | CKBox uses a globally distributed CDN to deliver files. Cached copies may reside outside the original region (uses AWS CloudFront). Cached content is automatically invalidated across all edge locations when an asset is removed or updated, making it no longer accessible. |
| **CKEditor CDN**                 | Serve CKEditor files (JS, CSS)                                           | No          | —                                                                                                                                                                                                                                              | —                                                                          | CKEditor's infrastructure in AWS Cloudfront                                                           | —                                                                                                                                                                                                                                                                              |
| **Usage Metering (UBB)**         | Track editor loads for license validation and billing                    | Yes         | Non-personal usage logs (e.g. editor load counts, license ID) stored for billing/support                                                                                                                                                       | License key and usage info sent on editor initialization (no user content) | CKEditor's infrastructure in AWS US East region                                                       | [Read more](#ckeditor5/latest/getting-started/licensing/usage-based-billing.html)                                                                                                                                                                                              |
| **Emoji Database**               | Provide emoji definitions (names, symbols, categories) to editor via CDN | No          | —                                                                                                                                                                                                                                              | —                                                                          | CKEditor's infrastructure in AWS Cloudfront                                                           | [Read more](#ckeditor5/latest/features/emoji.html--emoji-source)                                                                                                                                                                                                               |
| **Easy Image**                   | Image upload and automatic resizing service                              | Yes         | Uploaded images                                                                                                                                                                                                                                | Same as at rest                                                            | Selected cloud region [\[0\]](#cs/latest/guides/system-security.html--legend-0) ⚠️ See "Notes"        | ⚠️ Legacy service (not available to new customers). CKEditor Easy Image uses a globally distributed CDN to deliver files. Cached copies may reside outside the original region (uses AWS CloudFront).                                                                          |
| **Image Optimizer (Uploadcare)** | Premium feature provided by CKSource's partner Uploadcare                | Yes         | Uploaded files and their metadata                                                                                                                                                                                                              | Same as at rest                                                            | Storage and processing: AWS us-east-1 Cached versions of the files: Globally on Fastly and CloudFront | —                                                                                                                                                                                                                                                                              |
| **MathType / ChemType**          | Premium feature provided by CKSource's partner Wiris                     | —           | —                                                                                                                                                                                                                                              | —                                                                          | —                                                                                                     | The service is operated by Wiris. For additional information or assistance, please reach out to the Wiris support team.                                                                                                                                                        |
| **WProofreader**                 | Premium feature provided by CKSource's partner WebSpellChecker           | —           | —                                                                                                                                                                                                                                              | —                                                                          | —                                                                                                     | The service is operated by WebSpellChecker. For additional information or assistance, please reach out to the WebSpellChecker support team.                                                                                                                                    |

**LEGEND**  
**\[0\]** Selected cloud region: based on the region in which a particular environment was created (US or EU).

**\[1\]** Document content is stored either just for the length of a collaboration session duration with two exceptions:

* if Document storage is enabled – document content is stored permanently
* if the Revision history feature is used – content of document revisions is stored permanently

**\[2\]** The “Data in Transit” column describes the primary content of the transmitted payload (for example document content, license key). In addition to the payload, standard transport-layer metadata – such as the end user’s IP address, HTTP headers, and TLS handshake data – may also be transmitted as part of the communication process.

**\[3\]** In addition to the data processed and stored for providing the service, CKEditor Cloud Services also retains a subset of data for logging purposes:

* If a customer enables the Insights Panel, logs are collected and stored for 14 days, during which they are accessible to the customer for analysis.
* Operational logs are also collected and retained for a period of 90 days in AWS CloudWatch to support service delivery and maintenance by the CKEditor Cloud Services team.  
In both cases, log data is stored in the Selected cloud region \[0\].

**\[4\]** The data is encrypted at rest using AES-256 using separate encryption keys for each customer and environment. Read more in the [Data security and encryption](#cs/latest/guides/system-security.html--data-security-and-encryption) section.

<a id="cs/latest/guides/system-security.html--security-contact">

### Security Contact

If you have any questions or concerns about CKEditor Cloud Services’ security policies and practices, please get in touch with our team at [security@cksource.com](mailto:security@cksource.com).

<a id="cs/latest/index.html">source file: "cs/latest/index.html"</a>

## Cloud Services

CKEditor Cloud Services is a cloud platform for editing and real-time collaboration services. It serves as a supporting backend for selected rich text editing features available in CKEditor 5 and CKEditor 4.

<a id="cs/latest/index.html--documentation">

### Documentation

* [CKEditor Cloud Services guides](#cs/latest/guides/overview.html) – Learn how to connect to CKEditor Cloud Services and what services are available.
* [Export to PDF - Quick Start](#cs/latest/guides/export-to-pdf/quick-start.html) – Learn how to set up the PDF Converter service and connect it with CKEditor.
* [Export to Word - Quick Start](#cs/latest/guides/export-to-word/quick-start.html) – Learn how to set up the HTML do .DOCX Converter service and connect it with CKEditor.
* [Collaboration - Quick Start](#cs/latest/guides/collaboration/quick-start.html) – Learn how to set up the Collaboration service and connect it with CKEditor 5.
* [Developer Resources - Overview](#cs/latest/developer-resources/index.html) – Learn how to integrate your application with the CKEditor Cloud Services.
* [CKEditor Cloud Services On-Premises](#cs/latest/onpremises/overview.html) – Learn how to set up the On-Premises versions of CKEditor Cloud Services.
* [Examples](#cs/latest/examples/index.html) – Learn how to create token endpoints, webhooks and request signatures based on simple examples.

<a id="cs/latest/onpremises/ckbox-onpremises/api.html">source file: "cs/latest/onpremises/ckbox-onpremises/api.html"</a>

## CKBox On-Premises REST API usage

The Restful APIs feature is a part of the On-Premises version. It can be used to integrate your server application with CKBox.

The API is available on `http://localhost:[port]` (by default the `port` is `8080`).

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html">source file: "cs/latest/onpremises/ckbox-onpremises/cdn-integration.html"</a>

## CKBox On-Premises CDN integration

This guide will walk you through the process of integrating a Content Delivery Network (CDN) into the CKBox On-Premises application. A CDN helps optimize content delivery by distributing it across multiple servers globally, reducing load times and enhancing user experience.

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--cdn-setup">

### CDN setup

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--prerequisites">

#### Prerequisites

In order to set the CDN for CKBox On-Premises ensure you have:

1. Access to a CDN provider account (e.g., AWS CloudFront, Cloudflare, etc.).
2. A custom domain linked to your CKBox On-Premises (e.g. `https://yourdomain.com`).

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--infrastructure-setup">

#### Infrastructure setup

To set up CDN, first access your CDN provider’s dashboard, and create a new distribution (use web distribution or equivalent based on your provider).

After setting up the distribution, configure it to work with the CKBox On-Premises.

Set Origin Domain to your domain e.g. `https://yourdomain.com` which is linked to your On-Premises application.

After setting the origin domain you can optionally set custom domain names (CNAMEs) you want to use for the CDN e.g. `cdn.yourdomain.com`

Set the custom SSL Certificate if you have one, and apply changes to your distribution.

Depending on your CDN provider it may take some time for the distribution to become fully active.

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--define-cache-behaviors">

#### Define cache behaviors

In order to instruct CDN how to process specific requests, a cache behavior needs to be set. In your CDN provider dashboard navigate to Cache Behaviors Settings and choose Path Patterns. When CDN receives a viewer request, the requested path is compared with path patterns.

CKBox uses the following paths to serve optimized images that can be cached using CDN:

* `/*/assets/*/file` (this endpoint serves the contents of the original file asset with appropriate mime-type)
* `/*/assets/*/images/*` (this endpoint serves the responsive versions of images edited in CKEditor or embedded on the webpage)

Note: These specific paths are meant for caching to enhance performance for assets that do not frequently change. Caching dynamic or frequently updated content may result in stale data for users. Please note that only those two endpoints of CKBox On-Premises should be taken into account when defining caching paths.

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--set-cache-time">

#### Set cache time

Cache time / Edge cache TTL is recommended to be 7 days. This gives the best tradeoff between performance and freshness of content. A longer cache reduces the need for repeated requests to the origin server, improving the response time. It also allows relatively fresh content, striking a balance between performance and ensuring users receive updated assets in a reasonable time frame. Finally, longer cache times can lead to cost savings as there are fewer requests to the origin server.

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--set-assets-origin">

#### Set assets origin

In order to redirect traffic through the CDN, the URLs to the images must point to the CDN’s domain. To set up the assets origin URL please set the `ASSETS_ORIGIN` environment variable while running the On-Premises docker container e.g.:

```
docker run --init -p 8080:8080 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    ...
    -e ASSETS_ORIGIN=[your CDN domain e.g. cdn.yourdomain.com] \

```

<a id="cs/latest/onpremises/ckbox-onpremises/cdn-integration.html--cache-invalidation">

### Cache invalidation

Cache invalidation is currently supported in CKBox On-Premises only when using AWS CloudFront provider. Other CDN providers would require custom client implementation for CDN cache invalidation via CKBox Webooks.

To set up AWS CloudFront integration with CKBox On-Premises, set the required environment variables when running a docker container:

```
docker run --init -p 8080:8080 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    ...
    -e CDN_DRIVER="cloudfront" \
    -e CDN_REGION=[your AWS CloudFront region] \
    -e CDN_ACCESS_KEY_ID=[your AWS access key id] \
    -e CDN_SECRET_ACCESS_KEY=[your AWS secret key] \
    -e DISTRIBUTION_ID=[your distribution id] \

```

Assets invalidation happens specifically on asset overwrite. This can happen if the asset’s content is overwritten using `POST:*/assets/{assetId}` endpoint, or replaced while editing the image using CKBox image editor.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html">source file: "cs/latest/onpremises/ckbox-onpremises/changelog.html"</a>

## CKBox On-Premises

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--2103-2026-03-13">

### 2.10.3 (2026-03-13)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--bug-fixes">

#### Bug fixes

* Fixed webhooks retry mechanism  
An issue was discovered where webhooks were not being retried if the target receiver server returned an error response (non-2xx status code). This patch ensures that the retry mechanism correctly triggers according to the configuration, improving the reliability of event delivery to external services.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--2102-2026-01-29">

### 2.10.2 (2026-01-29)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--bug-fixes-2">

#### Bug fixes

* Improved Latin-1 Character Encoding  
Fixed an issue where Latin-1 Supplement characters were not correctly encoded in the `Content-Disposition` header,  
which could lead to improperly handled filenames.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-2">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--2101-2025-12-08">

### 2.10.1 (2025-12-08)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-3">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--2100-2025-12-02">

### 2.10.0 (2025-12-02)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features">

#### Features

* Added workspace list pagination and searching  
Added a new `GET:/v3/workspaces` endpoint that addresses performance issues and potential query timeouts  
when retrieving a large number of workspaces, and enables support for searching particular workspaces.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--bug-fixes-3">

#### Bug fixes

* Fixed AI reprocessing bug after image edit  
Fixed an issue where images uploaded before AI features were enabled were not sent for AI processing  
when edited and saved as a new asset in an AI-enabled workspace. The newly created asset now correctly  
triggers the AI processing workflow.
* Changed filename on download/view  
Fixed an issue where files served directly via their link used a generic filename (`file`) in the browser  
instead of using the original file’s name from the metadata. The original filename is now correctly used.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-4">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--290-2025-10-22">

### 2.9.0 (2025-10-22)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-2">

#### Features

* Added AI-powered features  
When enabled, image-like assets will receive automatically generated descriptions and tags via generative AI.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--bug-fixes-4">

#### Bug fixes

* Fixed asset restoration tags bug  
When an asset was restored from trash, its original tags could be overwritten. Now tags are correctly preserved and restored along with the asset.
* Fixed the problem with editing images in folders  
When an image in a folder was edited and saved as a new file, it could trigger validation errors. This issue has been fixed, and such operation now completes successfully.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-5">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--283-2025-09-02">

### 2.8.3 (2025-09-02)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--bug-fixes-5">

#### Bug fixes

* Fixed a problem with handling malformed `form-data` in private category authorization  
Previously, corrupted or incomplete form submissions caused an uncaught error. Such cases are now properly handled and return 400 Bad Request.
* Fixed a problem with invalid asset ID validation in image requests  
Requests with asset IDs that were too short or too long incorrectly returned 500 Internal Server Error. They now return the correct 400 Bad Request.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-6">

#### Other changes

* Improved and clarified REST API documentation for better developer experience
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--282-2025-07-22">

### 2.8.2 (2025-07-22)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes">

#### Fixes

* Fixed problem with MP4 files detection  
Previously the MP4 video files were incorrectly served with the `application/mp4` MIME type.  
Now the correct `video/mp4` MIME type is used.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-7">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--281-2025-07-01">

### 2.8.1 (2025-07-01)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-2">

#### Fixes

* Fixed Authorization for the Management Panel  
The Authorization for the Management Panel wasn’t verified properly.  
Now, the correct password is required to access the Management Panel.  
The issue was reported by Adam Wójs from [Ibexa](https://www.ibexa.co/). Thank you!

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--280">

### 2.8.0

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-3">

#### Features

* Added the Trash bin feature  
The new feature introduces a soft-delete mechanism for assets, allowing users to recover accidentally deleted files,  
auto-purge old items, and better manage asset lifecycle

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-3">

#### Fixes

* Fixed the problem with DISTRIBUTION\_ID configuration value being pulled incorrectly for CDN configuration in CKBox On-Premises  
The value of `CDN_SECRET_ACCESS_KEY` was used instead of the `DISTRIBUTION_ID` while initializing CloudFront invalidation requests.  
This caused a cache invalidation calls to fail with authorization errors and incorrect resource ARNs.  
The fix ensures that the correct `DISTRIBUTION_ID` is now used while performing the cache invalidation operations.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-8">

#### Other changes

* Updated NodeJS to version 22
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--272-2025-04-24">

### 2.7.2 (2025-04-24)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-4">

#### Fixes

* Fixed an issue where file uploads could fail in setups using AWS S3  
The bug made larger files impossible to upload to CKBox. This typically affected files over 5MB in size.  
It was caused by a changed mechanism for checking the integrity of multipart uploads in one of dependencies,  
leading to failed uploads without visible service interruptions.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--271-2025-04-22">

### 2.7.1 (2025-04-22)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-5">

#### Fixes

* Fixed handling streams and premature connection interruptions  
Fixed issues where uploads or downloads interrupted mid-process (e.g., closed tabs or dropped connections) could cause service instability.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-9">

#### Other changes

* Improved logging  
Introduced better log entries to enhance monitoring, debugging, and overall service observability.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--270-2025-03-11">

### 2.7.0 (2025-03-11)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-4">

#### Features

* Added explicit character set to the `Content-Type` header  
Character set information specifying the encoding standard for all text-based MIME types  
(e.g., `text/plain`, `text/html`) will be included in the `Content-Type` header to ensure  
proper character encoding interpretation.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-10">

#### Other changes

* Improved performance of workspaces  
Optimized workspace handling to reduce database load and enhance overall performance across  
multiple endpoints, resulting in faster response times and improved efficiency.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--262-2025-01-28">

### 2.6.2 (2025-01-28)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-11">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--261-2024-11-19">

### 2.6.1 (2024-11-19)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-12">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--260-2024-10-10">

### 2.6.0 (2024-10-10)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-5">

#### Features

* Added the ability to set a custom thumbnail for non-image assets  
Added a new endpoint `POST:/assets/{{assetId}}/thumbs` which allows to upload an image that would become a custom thumbnail for the asset.
* Added Private Categories  
The feature will give administrators the ability to mark certain categories of assets as private, restricting access to its content to selected users or groups, adding an additional layer of control over content sharing.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-13">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--250-2024-08-27">

### 2.5.0 (2024-08-27)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-6">

#### Features

* Introduced the Permissions feature  
Permissions enable fine-grained control over user access to specific features and actions. By assigning permissions, admins can regulate user interactions with assets, categories, and folders. Permissions introduce control over:

  * Accessing a Category
  * Creating an Asset
  * Deleting an Asset
  * Modifying an Asset
  * Modifying Asset Metadata
  * Creating a Folder
  * Modifying a Folder Metadata
  * Deleting a Folder
* Added a configuration option to indicate the maximum file size that CKBox can allow during upload  
A new CKBox On-Premises configuration option `max_file_size_in_bytes_limit` will allow to limit a maximum file upload size from the default 32GB limit to that indicated by the configuration.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-6">

#### Fixes

* Improved the performance of workspaces  
Workspace information is fetched in a more optimized way.
* Improved error handling in Webhooks feature
* Improved the performance of uploading multiple files to a folder  
Enhanced the upload progress of multiple files, especially when targeting folders.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--243-2024-07-16">

### 2.4.3 (2024-07-16)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-14">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--242-2024-06-04">

### 2.4.2 (2024-06-04)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-7">

#### Fixes

* Updated handling of asset mime-type during asset update  
Resolved an issue with updating mimetypes when asset data is updated. The mimetype will be correctly updated in accordance with the new file extension.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-15">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--241-2024-04-23">

### 2.4.1 (2024-04-23)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-16">

#### Other changes

* Improved overall performance  
Enhanced responsiveness and speed of particular actions.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--240-2024-03-12">

### 2.4.0 (2024-03-12)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-7">

#### Features

* Introduced Webhooks  
We have added support for webhooks within the application. By integrating Webhooks, third party apps will be able to be notified whenever:

  * an asset is modified,
  * an asset is overwritten,
  * an asset is copied,
  * an asset cache should be invalidated,
  * a folder is created,
  * a folder is modified,
  * a folder wis removed.
* Changed requirements for uploading files  
`categoryId` is required no more while uploading assets to CKBox. Both `categoryId` and `folderId` are now optional, and target upload category is deduced from the category settings defined by admins.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-8">

#### Fixes

* Fixed issues with requesting images with capitalized extensions  
Image URL containing capitalized extension such as `JPG` is now considered valid.
* Improved overall performance  
Enhanced responsiveness and speed of selected actions.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--231-2024-01-23">

### 2.3.1 (2024-01-23)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-9">

#### Fixes

* Fixed issues related to uploading huge files, resolving random timeout errors  
Increased actual upload timeout to 4 hours, ensuring successful completion of large file uploads without encountering timeout errors.
* Fixed problems with abruptly closed connections  
Implemented measures to prevent unexpected connection interruptions, properly handling abruptly closed connections, for example, while closing CKBox during upload.
* Improved overall performance  
Enhanced responsiveness and speed of the workspaces.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-17">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--230-2023-12-19">

### 2.3.0 (2023-12-19)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-18">

#### Other changes

* Improved integration with CKBox application  
Some of the internal mechanisms for workspaces were adapted to allow editing external web images via CKBox’s Image Editor.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--220-2023-11-14">

### 2.2.0 (2023-11-14)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-8">

#### Features

* Added an option to globally limit allowed extensions for all workspaces in the environment  
New endpoints for changing global extensions limits were added:

  * `GET:/admin/environmentConfig` returns an object describing environment extensions limit containing properties:

    * `allowedExtensions` which is an array of strings containing extensions that are allowed to upload in the environment
    * `isAllowedExtensionsEnabled` which is a flag indicating whether limiting extensions in the environment is enabled or disabled
  * `PUT:/superadmin/environmentConfig` allows to modify the configuration of allowed extensions for the entire environment  
  Note: The above endpoint is accessible for `SuperAdmin` users only.
* Extended the payload of the response of fetching workspaces list `GET:/workspaces`  
The endpoint will now include additional properties:

  * `allowedExtensions` is an array of strings containing all extensions that are allowed in all workspaces in the environment
  * `extensionsInUse` is an array of strings containing a list of the asset extensions that are currently in use for all workspaces in the environment  
Note: Extended response is accessible for `SuperAdmin` users only.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-10">

#### Fixes

* Improved performance of the assets processing
* Fixed the problem of uploading large files to CKBox  
Timeout issues during upload of files that could take >30 min to upload have been fixed.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-19">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--210-2023-09-27">

### 2.1.0 (2023-09-27)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-9">

#### Features

* Added global environment configuration management in CKBox  
New endpoints for changing global environment configuration were added:

  * `GET:/superadmin/workspacesTemplate` returns a list of categories that should be created in new workspaces created in the environment
  * `PUT:/superadmin/workspacesTemplate` allows to modify the list of categories created in a new workspace

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-11">

#### Fixes

* Fixed the problem with composite image editing operations  
Introduced version 2 of the image editing endpoint `POST:/assets/{assetId}/editImage` that preserves the order of the operations throughout all image file formats:

  1. Flip is applied before anything else.
  2. Then rotation is applied.
  3. Then crop is applied.
  4. Then resize is applied.  
This fixes the problem of incorrectly cropped image part if it was previously flipped or rotated.
* Fixed a problem while connecting with a database thru the TLS connection  
The TLS connection wasn’t possible, now TLS can be used properly.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-20">

#### Other changes

* Deprecated query parameter `workspaceId` in some of the assets-related endpoints  
The `workspaceId` parameter, which was previously used as a query parameter in our endpoints, has been deprecated and is not required anymore for the following endpoints: `GET:/assets/{assetId}/offset`, `POST:/assets/{assetId}`, `PATCH:/assets/{assetId}`, `PATCH:/assets/{assetId}/metadata`.
* Added validation rules for maximum width and height in Image Editing in CKBox  
Maximum edited image dimension (width or height) is now limited to `16383px`.
* Improved mechanism to release unused database connections
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--200-2023-08-22">

### 2.0.0 (2023-08-22)

Note: The CKBox On-premises 2.0.0 does not contain any breaking changes, the versioning is simply shared with the frontend part of the CKBox, which contains a breaking change.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-12">

#### Fixes

* Fixed the problem with handling files containing some of UNICODE combined accents in the filename
* Fixed problems with uploading multiple files at once in CKBox configuration with a Postgres database

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-21">

#### Other changes

* Adjusted the process of image editing  
The description and the tags assigned to an asset will now be copied to the newly created asset if the edited image is saved as a new file.
* Improved the performance of image rescaling  
Adjusted image processing to speed up image processing and increase the rescaling performance.
* Optimized CPU usage
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--160-2023-07-13">

### 1.6.0 (2023-07-13)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-10">

#### Features

* Added `metadataProcessingStatus` property to the asset’s metadata  
The new property provides information about the status of processing image metadata.
* Added the Asset overwrite feature  
A new `POST:/assets/:assetId` endpoint has been added to enable users to overwrite the asset’s file content.
* Added the Asset offset feature  
A new `GET:/assets/:assetId/offset` endpoint has been added providing functionality to determine the position offset of an asset in a category or folder based on specific sorting conditions.
* Added the Workspaces feature

Workspaces create completely separate instances of CKBox within one environment, which is effectively close to what can be achieved using separate environments.

Added 4 new endpoints dedicated to workspace management:

* `POST:/superadmin/workspaces` creates a new workspace within the environment
* `PUT:/superadmin/workspaces/:workspaceId` modifies the workspace
* `DELETE:/superadmin/workspaces/:workspaceId` deletes the workspace
* `GET:/workspaces` returns the list of all workspaces to which the user has access to
* Added the Image Editing feature:  
An image editing API allows to perform various operations on image assets. The editing operation can be performed via a new endpoint `POST:/assets/:assetId/edit`.  
Some common image operations supported by such an API include:

  * Crop: This operation can select a specified portion of an image, removing the rest of it. This helps focus on a particular subject or remove unwanted elements.
  * Resize: This operation allows to change the dimensions (width and height) of an image, either proportionally or by specifying custom dimensions.
  * Rotate: This operation enables the rotation of an image by a set angle. 90 degrees clockwise or counterclockwise.
  * Flip: Flipping allows the user to mirror an image horizontally or vertically

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-13">

#### Fixes

* Fixed Redis cluster TLS options  
Fixed TLS options for a Redis cluster to make the connection to a Redis cluster possible for on-premises.
* Improved the performance of image processing

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-22">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--150-2023-05-30">

### 1.5.0 (2023-05-30)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-11">

#### Features

* Added support for `REDIS_USER`  
The environmental variable allows to set the user while connecting to the Redis instance.  
More details can be found in the online documentation.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-14">

#### Fixes

* Fixed the asset metadata that used specific orientation  
CKBox will now correctly save metadata about the image’s dimensions, taking into account the orientation contained in the EXIF.
* Improved sample in API docs for the `POST:/assets` endpoint  
Adjusted the API docs sample to better reflect the interface of the data returned from the endpoint.
* Added REST API documentation for the copy/move feature  
The REST API documentation now contains detailed docs and samples for 3 new endpoints related to copying/moving assets in CKBox:

  * `POST:/assets/copy`
  * `POST:/assets/move`
  * `POST:/assets/namesExist`
* Improved the overall performance of copy/move operations
* Improved the error handling of corrupted or empty files

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--140-2023-04-18">

### 1.4.0 (2023-04-18)

The 1.3.0 version was skipped to unify the versioning of CKBox On-premises with the cloud-based application.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-12">

#### Features

* Added the Copy assets feature  
Assets can now be copied between categories and folders. A new `POST:/assets/copy` endpoint has been added to enable users to copy assets. This endpoint also supports the action (replace or rename) to be performed during the operation.
* Added the Move assets feature  
Assets can now be moved between categories and folders. A new `POST:/assets/move` endpoint has been added to enable users to move assets. This endpoint also supports the action (replace or rename) to be performed during the operation.
* Added the Assets exist feature  
A new `POST:/assets/namesExist` endpoint has been added, which can be used to check whether assets with the same names exist in the target location. Such operation becomes useful when resolving conflicts when copying or moving assets.
* Added the `parentId` property to the `GET:/folders/:folderId` endpoint response  
`GET:/folders/:folderId` will now include information about the identifier of the ancestor folder in each folder.
* Added the assets count in folders and categories  
The behavior of the `assetsCount` property in `GET:/categories/categoryId` has been changed to reflect the assets count only for that category, without descendants folders. Additionally, a new `totalAssetsCount` property has been added, providing the number of all assets, taking into account the descendant folders of a given category.
* Added the `assetsCount` property to the `GET:/folders/:folderId` endpoint  
The `GET:/folders/:folderId` endpoint now includes the additional `assetsCount` property containing the number of assets in that particular folder.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-15">

#### Fixes

* Ignored extension letter case when checking for allowed extensions  
Assets operations are now case-insensitive, it fixed some of the validation issues.
* Disabled signature check on the `/limits` endpoint
* Disabled marking assets as recent on `GET:/assets/:assetId` requests

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-23">

#### Other changes

* Improved API docs for folders
* Improved performance of counting assets
* Improved performance of processing GIFs and BMP
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--120-2023-02-28">

### 1.2.0 (2023-02-28)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-13">

#### Features

* Added natural sorting to folders  
Folders returned on all REST API endpoints are now sorted in the natural order.
* Added possibility to return descendants to n-depth when retrieving folder branch  
`GET:/folder/:folderId/branch` endpoint will now accept an additional query parameter `depth` which will control the depth of the returned folder tree.
* Included `categoryId` in assets and folder objects in subfolders  
All folders within the folder structure will now include additional information about the parent category. Before this information was only returned to the root folders.
* Removed `GET /assets/:assetId/metadata` endpoint from REST API  
The `GET /assets/:assetId/metadata` endpoint for returning metadata for the asset is now deprecated and no longer operational.
* Removed property `categoryId` from the `PATCH /assets/:assetId` endpoint  
The `categoryId` property was removed from the supported payload properties in that endpoint.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--fixes-16">

#### Fixes

* Fixed an issue related to uploading the wrong `Content-Type` payload to CKBox
* Fixed an issue with response hangup upon sending empty JSON to `POST:/search`
* Fixed an issue related to validation mismatch when uploading a file to a folder

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-24">

#### Other changes

* Added REST API documentation for the folders feature

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--110-2023-01-23">

### 1.1.0 (2023-01-23)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-14">

#### Features

* Added the `/search` API  
The new `/search` API allows searching assets by various properties like name, category, tags, and time range.  
More information can be found in the CKBox REST API documentation.
* Added `tags` property to assets  
The new property allows for classifying your assets by tags.  
The tags are added to asset responses and can be used to filter search results.
* Added metrics logs  
The new logs allow monitoring of the performance and stability of the CKBox On-premises.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--other-changes-25">

#### Other changes

* Improved UX of the Insight Panel view in the management panel  
It is now possible to set a relative time frame for logs, so e.g. logs from the last hour can be checked.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--100-2022-09-09">

### 1.0.0 (2022-09-09)

<a id="cs/latest/onpremises/ckbox-onpremises/changelog.html--features-15">

#### Features

* Added On-Premise version of CKBox.  
The service allows for managing file assets and providing responsive versions of images.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html">source file: "cs/latest/onpremises/ckbox-onpremises/configuration.html"</a>

## Configuration

You can configure CKBox On-Premises using environment variables. Below you will find available environment variables with descriptions.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--secret-keys">

### Secret keys

The `license_key` variable is used to verify that you own the rights to run CKBox On-Premises. To get your `license_key` please [contact us](https://ckeditor.com/contact/). If you leave this option empty or provide an invalid key, CKBox On-Premises will not launch.

The `environments_management_secret_key` variable should be a hard to guess string, preferably generated by an external password generator. It will be used to access the [Cloud Services Management Panel](#cs/latest/onpremises/cs-onpremises/management.html).

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--sql-database">

### SQL Database

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--mysql-database">

#### MySQL database

To configure the MySQL database you should first set the `database_driver` variable to `mysql`.

Then, you can provide:

* `database_host` and `database_port` to configure the database address.
* `database_user` and `database_password` to configure the database user.
* `database_database` to set the database that should be used by CKBox On-Premises.

If your database connection should be encrypted, use the `database_ssl_ca`, `database_ssl_key` and `database_ssl_cert` configurations.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--postgres-database">

#### Postgres database

To configure the Postgres database instead of MySQL, you should first set the `database_driver` variable to `postgres`.

Then, you can provide:

* `database_host` and `database_port` to configure the database address.
* `database_user` and `database_password` to configure the database user.
* `database_database` and `database_schema` to point which schema should be used by the On-Premises server.

If your database connection should be encrypted, use the `database_ssl_ca`, `database_ssl_key` and `database_ssl_cert` configurations.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--redis-database">

### Redis database

Besides the SQL database, you need to configure the Redis database using:

* `redis_host` and `redis_port` to configure the database address.
* `redis_password` and `redis_user` to configure the database credentials. Both configuration options are optional.

You can also provide `redis_db` if you don’t want to use the default database number, which is set to `1`.

If you have a problem with connecting to IPv6, try setting `redis_ip_family` to `6`.

If your database connection should be encrypted, use the `redis_tls_ca`, `redis_tls_key`, and `redis_tls_cert` configurations, or set `redis_tls_enable` to `true` if you don’t use a custom certificate.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--connecting-to-redis-cluster">

### Connecting to Redis Cluster

To set up a connection with a Redis Cluster, nodes need to be provided as the `REDIS_CLUSTER_NODES` variable.

```
REDIS_CLUSTER_NODES        - required (for Redis Cluster connection)
REDIS_IP_FAMILY            - optional (required only when using an IPv6 domain in `REDIS_CLUSTER_NODES`)

```

The `REDIS_CLUSTER_NODES` variable needs to contain a list of nodes in the dedicated format, which consists of:

```
"IP:PORT:[optional PASSWORD],IP:PORT:[optional PASSWORD]"

```

To understand the connection string format, check the examples below:

```
# IPv6
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000,[0:0:0:0:0:0:0:1]:7001,[0:0:0:0:0:0:0:1]:7002"

# IPv6 with a password
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000:password1,[0:0:0:0:0:0:0:1]:7001:password2,[0:0:0:0:0:0:0:1]:7002:password3"

# Domain name
REDIS_CLUSTER_NODES: "example.redis.server.com:7000,example.redis.server.com:7001,example.redis.server.com:7002"

# Domain name with IPv6 support
REDIS_IP_FAMILY: 6
REDIS_CLUSTER_NODES: "example.ipv6.redis.server.com:7000,example.ipv6.redis.server.com:7001,example.ipv6.redis.server.com:7002"

# Domain name with a password
REDIS_CLUSTER_NODES: "example.redis.server.com:7000:password1,example.redis.server.com:7001:password2,example.redis.server.com:7002:password3"

```

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--storage">

### Storage

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--s3-storage">

#### S3 storage

To configure S3 as your files storage you should first set the `storage_driver` variable to `s3`.

Then, you can provide:

* `storage_access_key_id` and `storage_secret_access_key` to authorize the service.
* `storage_bucket` to set the bucket where the files should be stored.

If you use an S3 compatible server, you can set the address with `storage_endpoint` variable.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--azure-blob-storage">

#### Azure Blob Storage

To configure Azure Blob Storage as your files storage you should first set the `storage_driver` variable to `azure`.

Then, you can provide:

* `storage_account_name` and `storage_account_key` authorize to the service.
* `storage_container` to set the container where the files should be stored.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--filesystem">

#### Filesystem

To configure the filesystem as your files storage you should first set the `storage_driver` variable to `filesystem`.

Then you can provide the path to the directory where the files should be stored using the `storage_location` variable.

<a id="cs/latest/onpremises/ckbox-onpremises/configuration.html--sql-storage">

#### SQL storage

To configure MySQL or Postgres as your files storage, you should set the `storage_driver` variable to `database`. When using SQL as a storage driver, the application will use the configuration provided in the `database_*` variables.

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html">source file: "cs/latest/onpremises/ckbox-onpremises/deployment.html"</a>

## Deployment

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html--infrastructure">

### Infrastructure

To run CKBox on your server, you need to have certain services prepared first:

* An SQL database (MySQL and Postgres are supported)
* A Redis database
* Data storage (S3, Azure Blob Storage, filesystem, MySQL, or Postgres)

Besides, you need an Open Container runtime to run CKBox. You can use, among others: Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances.

We also recommend using a load balancer. You can use almost any load balancer you choose, like NGINX, HAProxy, Amazon Elastic Load Balancing, or Azure Load Balancer. Thanks to this, you will be able to create TLS connections and run several cooperating instances of CKBox On-Premises. It will increase the security and the performance of the application.

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html--sql-database">

#### SQL Database

The SQL database stores persistent data like the configurations of categories, assets metadata, environments information, etc.

It can also be used as a data storage for your assets, but due to the SQL database limitations, the largest file you can send is 4GB. For this reason, we recommend using different storage drivers that can handle bigger files, like S3, Azure Blob Storage or a filesystem.

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html--mysql">

##### MySQL

The minimum required version of MySQL is 5.7, while MySQL in version 8.0 is both supported and recommended. The database and user should have at least the following privileges: `ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, TRIGGER, UPDATE, LOCK TABLES, REFERENCES`.

If you plan to use the MySQL database as a blob storage, increase the `max_allowed_packet` parameter:

```
set global max_allowed_packet = 209715200;

```

The database should be created before running CKBox On-Premises. An example database creation script:

```
CREATE DATABASE `ckbox-on-premises`
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_bin;

```

If you want to use another SQL database like Microsoft SQL Server, etc., please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html--postgresql">

##### PostgreSQL

The minimum required version of PostgreSQL is 12.0\. The database and user should have at least the following privileges: `SELECT, INSERT, UPDATE, DELETE, REFERENCES, CREATE, USAGE`.

The database with a schema should be created before running CKBox On-Premises. An example database and schema creation script:

```
CREATE DATABASE "cksource";
\connect "cksource";
CREATE SCHEMA "ckbox-on-premises";

```

<a id="cs/latest/onpremises/ckbox-onpremises/deployment.html--running-the-service">

### Running the service

After meeting all infrastructure requirements, you can prepare the CKBox application to run.

Follow the steps below to install CKBox On-Premises using the Docker image.

* Use the instructions below to log into the `CKBox On-Premises` Docker Registry and pull the Docker image. To get the `DOWNLOAD_TOKEN` go to the [Customer Portal](https://portal.ckeditor.com) and navigate to Subscription -> License Keys.

```
docker login -u ckbox -p [DOWNLOAD_TOKEN] https://docker.cke-cs.com
docker pull docker.cke-cs.com/ckbox:latest

```

* Launch the Docker container (you can find all the configuration options in [the Configuration section](#cs/latest/onpremises/ckbox-onpremises/configuration.html)):

```
docker run --init -p 8080:8080 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your management secret key used in management panel] \
    -e DATABASE_DRIVER=[mysql|postgres] \
    -e DATABASE_HOST=[your database host] \
    -e DATABASE_USER=[your database user] \
    -e DATABASE_PASSWORD=[your database user password] \
    -e DATABASE_DATABASE=[your database name] \
    -e REDIS_HOST=[your redis host] \
    -e STORAGE_DRIVER=[s3|azure|filesystem|database] \
    -e STORAGE_ACCESS_KEY_ID=[your AWS access key] \
    -e STORAGE_SECRET_ACCESS_KEY=[your AWS secret key] \
    -e STORAGE_BUCKET=[your S3 bucket name] \
    docker.cke-cs.com/ckbox:[version]

```

* Create the `Environment` with an `Access Key` via the [Cloud Services Management Panel](#ckbox/latest/guides/configuration/authentication.html). To access the management panel, use `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` you provided to the container. Then, use your `Environment ID` and `Access Key` created in the panel to [create the token endpoint](#ckbox/latest/guides/configuration/authentication.html--token-endpoint).
* Set `serviceOrigin` and `assetsOrigin` in [CKBox configuration options](#ckbox/latest/guides/configuration/configuration-options.html--serviceorigin) to your server URL.

<a id="cs/latest/onpremises/ckbox-onpremises/index.html">source file: "cs/latest/onpremises/ckbox-onpremises/index.html"</a>

## CKBox On-Premises

The On-Premises version of CKBox is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKBox available as SaaS.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/ckbox-onpremises/overview.html) – An introduction to CKBox On-Premises.
* [Deployment](#cs/latest/onpremises/ckbox-onpremises/deployment.html) – Learn how to install CKBox On-Premises.
* [API](#cs/latest/onpremises/ckbox-onpremises/api.html) – Learn how to use the CKBox REST API.
* [Configuration](#cs/latest/onpremises/ckbox-onpremises/configuration.html) – Learn how to configure CKBox On-Premises.
* [SSL communication](#cs/latest/onpremises/ckbox-onpremises/ssl.html) – Learn how to set up secure communication with CKBox On-Premises.
* [Logs](#cs/latest/onpremises/ckbox-onpremises/logs.html) – Learn how to manage the logs of CKBox On-Premises.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html">source file: "cs/latest/onpremises/ckbox-onpremises/logs.html"</a>

## CKBox On-Premises logs

The logs from CKBox On-Premises are written to `stdout` and `stderr`. Most of them are formatted in JSON. They can be used for monitoring or debugging purposes. In production environments, we recommend storing the logs to files or using a distributed logging system (like ELK or CloudWatch).

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--monitoring-ckbox-with-logs">

### Monitoring CKBox with logs

To get more insight into how the CKBox On-Premises is performing, we built logs that can be used for monitoring. To enable these, just add the `ENABLE_METRIC_LOGS=true` environment variable.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--log-structure">

#### Log structure

The log structure contains the following information:

* `handler` – A unified identifier of action. Use this field to identify calls.
* `traceId` – A unique RPC call ID.
* `tags` – A semicolon-separated list of tags. Use this field to filter metrics logs.
* `data` – An object containing additional information. It might vary between different transports.
* `data.duration` – The request duration in milliseconds.
* `data.transport` – The type of the request transport. It could be `http` or `ws` (websocket).
* `data.status` – The request status. It can be equal to `success`, `fail`, `warning`.
* `data.statusCode` – The response status in HTTP status code standard.

Additionally, for the HTTP transport, the following information is included:

* `data.url` – The URL path.
* `data.method` – The request method.

In case of an error, `data.status` will be equal to `failed` and `data.message` will contain the error message.

An example log for HTTP transport:

```
{
    "level": 30,
    "time": "2021-03-09T11:15:09.154Z",
    "msg": "Request summary",
    "handler": "ckbox",
    "traceId": "85f13d92-57df-4b3b-98bb-0ca41a5ae601",
    "data": {
        "duration": 2470,
        "transport": "http",
        "statusCode": 200,
        "status": "success",
        "url": "/assets",
        "method": "POST"
    },
    "tags": "metrics"
}

```

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--docker">

### Docker

Docker has a built-in logging mechanisms that capture logs from the containers’ output. The default logging driver writes these logs to files.

When using this driver, you can use the `docker logs` command to show logs from a container. You can add the `-f` flag to view logs in real time. Refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/logs/) for more information about the `logs` command.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--distributed-logging">

### Distributed logging

If you are running more than one instance of CKBox On-Premises, we recommend using a distributed logging system. It allows you to view and analyze logs from all instances in one place.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--aws-cloudwatch-and-other-cloud-solutions">

#### AWS CloudWatch and other cloud solutions

If you are running CKBox On-Premises in the cloud, the simplest and recommended way is to use a service which is available from your selected provider. Here are some of the available services:

* AWS – [CloudWatch](https://aws.amazon.com/CloudWatch)
* Google Cloud – [Cloud Logging](https://cloud.google.com/logging)
* Azure – [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/)

To use CloudWatch with AWS ECS, you have to create a log group first and change the log driver to `awslogs`. When the log driver is configured properly, logs will be streamed directly to CloudWatch.

The `logConfiguration` may look similar to this:

```
"logConfiguration": {
    "logDriver": "awslogs",
    "options": {
        "awslogs-region": "us-west-2",
        "awslogs-group": "cksource",
        "awslogs-stream-prefix": "ck-ckbox-logs"
    }
}

```

Refer to the [Using the awslogs Log Driver](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using%5Fawslogs.html) article for more information.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--on-premises-solutions">

#### On-Premises solutions

If you are using your own infrastructure or, for some reason, cannot use the service offered by your provider, you can always use some on-premises distributed logging system.

There are a lot of solutions available, including:

* [ELK](https://www.elastic.co/what-is/elk-stack) \+ [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html)  
This is a stack built on top of Elasticsearch, Logstash, and Kibana. In this configuration, Elasticsearch stores logs, Filebeat reads the logs from Docker and sends them to Elasticsearch, and Kibana is used to view them. Logstash is not necessary because the logs are already structured.
* [Fluentd](https://www.fluentd.org/)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/fluentd) to send the logs. It has a built-in frontend, but can also be integrated with Elasticsearch and Kibana for better filtering.
* [Graylog](https://www.graylog.org)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/gelf) to send the logs. It has a built-in frontend and needs Elasticsearch to store the logs as well as a MongoDB database to store the configuration.

<a id="cs/latest/onpremises/ckbox-onpremises/logs.html--example-configuration">

##### Example configuration

The example configuration uses Fluentd, Elasticsearch and Kibana to capture logs from Docker.

Before running CKBox On-Premises, you have to prepare the logging services. For the purposes of this example, Docker Compose is used. Create the `fluentd`, `elasticsearch` and `kibana` services inside the `docker-compose.yml` file:

```
version: '3.7'
services:
    fluentd:
        build: ./fluentd
        volumes:
            - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
        ports:
            - "24224:24224"
            - "24224:24224/udp"

    elasticsearch:
        image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
        expose:
            - 9200
        ports:
            - "9200:9200"

    kibana:
        image: docker.elastic.co/kibana/kibana:6.8.5
        environment:
            ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
        ports:
            - "5601:5601"

```

To integrate Fluentd with Elasticsearch, you first need to install `fluent-plugin-elasticsearch` in the Fluentd image. To do this, create a `fluentd/Dockerfile` with the following content:

```
FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
    && gem install fluent-plugin-elasticsearch \
    && gem sources --clear-all

```

Next, configure the input server and connection to Elasticsearch in the `fluentd/fluent.conf` file:

```
<source>
    @type forward
    port 24224
    bind 0.0.0.0
</source>
<match *.**>
    @type copy
    <store>
        @type elasticsearch
        host elasticsearch
        port 9200
        logstash_format true
        logstash_prefix fluentd
        logstash_dateformat %Y%m%d
        include_tag_key true
        type_name access_log
        tag_key @log_name
        flush_interval 1s
    </store>
    <store>
        @type stdout
    </store>
</match>

```

Now you are ready to run the services:

```
docker-compose up --build

```

When the services are ready, you can finally start CKBox On-Premises.

```
docker run --init -p 8080:8080 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
docker.cke-cs.com/ckbox:[version]

```

Now open Kibana in your browser. It is available at <http://localhost:5601/>. In the first run, you may be asked about creating an index. Use the `fluentd-*` pattern and press the “Create” button. After this step, your logs should appear in the “Discover” tab.

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html">source file: "cs/latest/onpremises/ckbox-onpremises/nightly-releases.html"</a>

## Nightly releases

This article describes the purpose and usage of nightly releases of CKBox On-Premises images.

Nightly images are released every day. During the automatic release, we run our tests to make sure that these images are working correctly, but unlike stable releases, nightly builds do not go through our full release process and are not tested and approved by our Quality Assurance.

Nightly images include all of the changes that are merged on our development branches. This allows you to access new features or receive fixes faster than with stable on-premises images.

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html--dangers-of-using-nightly-builds">

### Dangers of using nightly builds

Nightly builds are released automatically. By the nature of these images, they should be treated as unstable. Running an On-Premises application using these images may result in some unexpected behaviors, undocumented features or known and unknown defects.

You need to ensure that the versions that you are willing to run are working correctly and will not impact your application negatively. We highly recommend using DEV/UAT environments first and going through the process of quality acceptance on your side, before you use nightly images in production.

By using the nightly builds you accept the risks mentioned in the documentation.

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html--nightly-images-usage">

### Nightly images usage

There is a difference between the usage of nightly and stable releases of CKBox On-Premises. Instead of the `ckbox` image, you should use the `ckbox-nightly` images. Notice that the version of nightly images also includes a date and a hash. This date part can help you find the latest version of the nightly build. Example usage:

```
version: "2.2"
services:
    ckbox-nightly:
        image: docker.cke-cs.com/ckbox-nightly:2.3.1-20240227-a846c6d954 # change the version
        ports:
        - "8080:8080"
        # environment variables and other configuration

```

Nightly builds are available only as Docker images.

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html--list-of-available-nightly-versions">

### List of available nightly versions

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html--nightly-versions">

<a id="cs/latest/onpremises/ckbox-onpremises/nightly-releases.html--fetching-the-latest-nightly-version">

### Fetching the latest nightly version

If you want to automate the process of updating your application and automatically use the latest versions of nightly builds you can make a GET request at <https://docker.cke-cs.com/api/versions/ckbox-nightly>. This will fetch the JSON with all available versions. Use the date in the version to find the latest image that can be used in your application.

<a id="cs/latest/onpremises/ckbox-onpremises/overview.html">source file: "cs/latest/onpremises/ckbox-onpremises/overview.html"</a>

## CKBox On-Premises - overview

The On-Premises version of the CKBox is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKBox available as SaaS.

The documentation in this section refers to the simplified version of the CKBox On-Premises which was designed to be easy to set up and maintain (while preserving all the features). It also lowers the running costs by reducing the number of servers required to run the whole application to the minimum.

The CKBox On-Premises installation requires two servers: one for running the application (the “Application Server”) and another one for hosting the databases (the “Database Server”).

The CKBox On-Premises is distributed as a Docker Image. It can be used with any Open Container runtime, like Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances.

<a id="cs/latest/onpremises/ckbox-onpremises/overview.html--next-steps">

### Next steps

Read [how to deploy CKBox On-Premises](#cs/latest/onpremises/ckbox-onpremises/deployment.html).

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html">source file: "cs/latest/onpremises/ckbox-onpremises/requirements.html"</a>

## Requirements

This article describes the requirements necessary for CKBox On-Premises to run smoothly.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--ckbox-on-premises">

### CKBox On-Premises

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--hardware-requirements">

#### Hardware requirements

It is impossible to provide a single infrastructure setup, that will fit all use cases. In this section, we provide recommendations for ensuring high availability and high performance of CKBox On-Premises. As every use case is different, you need to monitor your application and adjust the infrastructure to your needs.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--high-availability">

##### High availability

To ensure high availability, we recommend running at least 3 instances of CKBox On-Premises.

CKBox On-Premises can be scaled with Docker containers on a single host machine. However, we recommend scaling on at least three host machines to provide the reliability of the system.

A load balancer, like HAProxy or NGINX (see the load balancer configuration examples in the [Reverse proxy](#cs/latest/onpremises/cs-onpremises/reverse-proxy.html) guide), is required for scaling on several machines. Of course, it is possible to use any cloud provider for scaling, such as Amazon ECS, Azure Container Instances, or Kubernetes.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--software-requirements">

#### Software requirements

Currently, we only provide Linux-based Docker images for CKBox. We highly recommend running these on machines with Linux. However, you can also use Docker Desktop to run our Docker images on other operating systems.

The application is provided as a Docker image by default.

It can be run with any Open Container runtime tool, for example: [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

In the case of Windows machines, you need to enable the [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/about#what-is-wsl-2) backend and switch to Linux containers. Make sure that your operating system supports such an option. Refer to the [Docker Desktop installation guide](https://docs.docker.com/desktop/windows/install/) for more information.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--sql-database">

### SQL Database

CKBox On-Premises requires MySQL database in version 8.0 or Postgres PostgreSQL 12.0.  
If you want to use another SQL database like Microsoft SQL Server, etc., please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--containers">

#### Containers

Databases can be launched as containers, but this requires high awareness and responsiveness. Because each company has different policies and arrangements, we do not recommend any approach and leave the decision as to how the databases will be launched to you.

However, we encourage you to read this article: [“To run or not to run a database on Kubernetes: What to consider”](https://cloud.google.com/blog/products/databases/to-run-or-not-to-run-a-database-on-kubernetes-what-to-consider) before making a decision.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--redis">

### Redis

The required Redis version for CKBox On-Premises is 3.2.6 or newer. CKBox supports connection to single instance Redis or Redis Cluster. Redis Sentinel is not supported.

<a id="cs/latest/onpremises/ckbox-onpremises/requirements.html--storage-system">

### Storage system

Storage systems that can be used with CKBox On-Premises are:

* AWS S3,
* Azure Blob Storage,
* Filesystem,
* SQL databases (the largest file you can send using SQL database is 4GB).

<a id="cs/latest/onpremises/ckbox-onpremises/ssl.html">source file: "cs/latest/onpremises/ckbox-onpremises/ssl.html"</a>

## CKBox On-Premises SSL communication

You can communicate with CKBox On-Premises using secure connections. To achieve this, you need to set up a load balancer like `NGINX` or `HAProxy` with your SSL certificate.

You can find the `HAProxy` and `NGINX` configuration examples below.

<a id="cs/latest/onpremises/ckbox-onpremises/ssl.html--haproxy-example">

### `HAProxy` example

Here is a basic `HAProxy` configuration:

```
global
    daemon
    maxconn 256
    tune.ssl.default-dh-param 2048

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/your_certificate.pem
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
    redirect scheme https if !{ ssl_fc }

    default_backend servers

backend servers
    server server1 127.0.0.1:8080 maxconn 32

```

<a id="cs/latest/onpremises/ckbox-onpremises/ssl.html--nginx-example">

### `NGINX` example

Here is a basic `NGINX` configuration:

```
events {
    worker_connections  1024;
}

http {
    server {
        server_name your.domain.name;

        listen 443;
        ssl on;
        ssl_certificate /etc/ssl/your_cert.crt;
        ssl_certificate_key /etc/ssl/your_cert_key.key;

        location / {
            proxy_pass http://127.0.0.1:8080;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
        }
    }
}

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/api.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/api.html"</a>

## CKEditor AI On-Premises REST API usage

The Restful APIs feature is a part of the On-Premises version. It can be used to integrate your server application with the CKEditor AI On-Premises.

The API is available on `http://localhost:[port]` (by default the `port` is `8000`). You can overwrite the `port` value by setting `application_http_port` configuration variable.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html"</a>

## Architecture

This article describes the recommended architecture for infrastructure that should be prepared for CKEditor AI On-Premises to run smoothly.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--overview">

### Overview

The CKEditor AI On-Premises infrastructure consists of two layers. The **application layer** runs the AI service provided as a Docker image. The **data layer** hosts the SQL database, Redis, and file storage. The application layer communicates with LLM providers (such as OpenAI, Anthropic, or Google) to process AI requests.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--application-layer">

### Application layer

The application layer consists of one or more application server instances and, optionally, a load balancer.

Each application server runs the CKEditor AI On-Premises Docker image. You can use any Open Container runtime: Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances.

When running multiple instances, a load balancer distributes incoming requests across them. You can use NGINX, HAProxy, Amazon Elastic Load Balancing, Azure Load Balancer, or any other solution of your choice. Running multiple instances behind a load balancer improves both availability and performance.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--data-layer">

### Data layer

The data layer consists of an SQL database, a Redis instance, and file storage.

**SQL database** (MySQL 8+ or PostgreSQL 12+) stores persistent data: configurations, conversations, files, and documents. The database should be created before starting the application. Refer to the [Deployment guide](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--sql-database) for database creation scripts.

**Redis** (version 3.2.6 or newer) handles temporary data and inter-instance communication for scaling. When multiple application instances are running, Redis ensures that data is shared correctly across all of them.

**File storage** holds uploaded files and documents. Supported backends are Amazon S3, Azure Blob Storage, the local filesystem, or the SQL database itself. See the [Configuration guide](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--storage) for details.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--llm-providers">

### LLM providers

CKEditor AI On-Premises connects to external LLM providers to process AI requests. At least one provider must be configured. Supported providers:

* **OpenAI** – GPT family models.
* **Anthropic** – Claude family models.
* **Google** – Gemini family models.
* **Azure OpenAI** – OpenAI models hosted on Azure (via the OpenAI-compatible interface).
* **Amazon Bedrock** – Models available through AWS Bedrock.
* **Google Vertex AI** – Models available through Google Cloud Vertex AI.
* **Custom providers** – Any other OpenAI API-compatible endpoint.

The application sends requests to provider APIs over HTTPS. Make sure that outbound HTTPS traffic from the application servers to the provider endpoints is allowed by your firewall rules.

For provider configuration details, see [LLM Providers](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--llm-providers).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--observability">

### Observability

CKEditor AI On-Premises supports [OpenTelemetry](https://opentelemetry.io/) instrumentation for monitoring AI interactions, token usage, and service health. Trace data can be exported to any OTLP-compatible backend (such as Jaeger, Grafana Tempo, or Datadog) and, optionally, to [Langfuse](https://langfuse.com/) for AI-specific insights. Both exports can run simultaneously.

When enabled, the application layer makes outbound HTTPS connections to the configured telemetry backends. Make sure the corresponding endpoints are reachable from your application servers.

For configuration details, see the [Observability](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html) guide.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--integration-with-collaboration-server-on-premises">

### Integration with Collaboration Server On-Premises

CKEditor AI On-Premises can share its data layer with [Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/overview.html). When integrated, both services use the same SQL database and Redis instance — they do not require separate databases. Environments and access keys created in the Collaboration Server Management Panel are automatically available to CKEditor AI On-Premises.

For step-by-step integration instructions, see [Integration with Collaboration Server On-Premises](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--integration-with-collaboration-server-on-premises).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html--next-steps">

### Next steps

* [Deployment](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html) – Install and run CKEditor AI On-Premises.
* [Requirements](#cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html) – Check hardware and software requirements.
* [Configuration](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html) – Configure the application.
* [Observability](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html) – Monitor AI interactions and service health.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html"</a>

## CKEditor AI On-Premises

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html--510-2026-04-14">

### 5.1.0 (2026-04-14)

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html--features">

#### Features

* Dedicated support for cloud providers  
Improved support for leading cloud providers. It is now possible to easily connect models from:

  * Vertex AI
  * Amazon Bedrock
  * Azure OpenAI
* Added OpenTelemetry observability support  
The service now supports OpenTelemetry instrumentation, enabling monitoring of AI interactions, token usage, and response quality, as well as HTTP calls and database operations, and is compatible with observability platforms such as Langfuse.
* New AI models support added

  * Claude 4.6 Sonnet (replaced 4.5 Sonnet in the recommended models list)
  * GPT-5.4 (replaced GPT-5.2 in the recommended models list)
  * GPT-5.4 Mini
  * Gemini 3.1 Pro
* New endpoint for listing documents of a conversation  
Added a new, paginated endpoint (`GET /v1/conversations/:conversationId/documents`) which allows listing all documents belonging to the conversation.
* New endpoint for getting file metadata  
Added a new endpoint that allows retrieving metadata for uploaded files without downloading the full content.
* Conversation sorting by `pinned` status  
Conversations can now be sorted by their `pinned` status, with pinned conversations appearing first.
* Increased maximum non-image file size to 25 MB  
The maximum size for a single non-image file has been increased from 5 MB to 25 MB. The Anthropic-specific 5 MB restriction now applies only to images, not all files. The total size limit for all files remains at 30 MB.
* Improved AI model failover reliability  
The service now recovers faster and more gracefully when an AI provider experiences outages.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html--fixes">

#### Fixes

* Improved reasoning and web search capabilities  
The AI Service has better guidance on when and how to use reasoning and web search capabilities, resulting in more effective responses.
* Improved AI Quick Actions suggestions to produce more reliable results  
In some cases, AI Quick Actions were producing incorrect suggestions and were falling into repetitive stream loops. This has been fixed.
* Improved PDF parsing performance  
Resolved performance issues with PDF file parsing that could cause slow processing.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html--other-changes">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/changelog.html--500-2026-03-03">

### 5.0.0 (2026-03-03)

Initial release of the CKEditor AI On-Premises.  
The version was synchronized with the CKEditor Collaboration Server On-Premises to  
ensure and underline the compatibility of the two applications.

It is highly recommended to synchronize the version of the CKEditor AI On-Premises with  
the CKEditor Collaboration Server On-Premises to ensure the compatibility of the two applications.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html"</a>

## Configuration

You can configure CKEditor AI On-Premises using environment variables. Below you will find available environment variables with descriptions.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--secret-keys">

### Secret keys

The `license_key` variable is used to verify that you own the rights to run CKEditor AI On-Premises. To get your `license_key`, please [contact us](https://ckeditor.com/contact/). If you leave this option empty or provide an invalid key, CKEditor AI On-Premises will not launch.

The `environments_management_secret_key` variable should be a hard-to-guess string, preferably generated by an external password generator. It will be used to access the [Cloud Services Management Panel](#cs/latest/onpremises/cs-onpremises/management.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--sql-database">

### SQL Database

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--mysql-database">

#### MySQL database

To configure the MySQL database, you should first set the `database_driver` variable to `mysql`.

Then, you can provide:

* `database_host` and `database_port` to configure the database address.
* `database_user` and `database_password` to configure the database user.
* `database_database` to set the database that should be used by CKEditor AI On-Premises.

If your database connection should be encrypted, use the `database_ssl_ca`, `database_ssl_key`, and `database_ssl_cert` configurations.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--postgres-database">

#### Postgres database

To configure the Postgres database instead of MySQL, you should first set the `database_driver` variable to `postgres`.

Then, you can provide:

* `database_host` and `database_port` to configure the database address.
* `database_user` and `database_password` to configure the database user.
* `database_database` and `database_schema` to indicate which schema should be used by the On-Premises server.

If your database connection should be encrypted, use the `database_ssl_ca`, `database_ssl_key`, and `database_ssl_cert` configurations.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--redis-database">

### Redis database

Besides the SQL database, you need to configure the Redis database using:

* `redis_host` and `redis_port` to configure the database address.
* `redis_password` and `redis_user` to configure the database credentials. Both configuration options are optional.

You can also provide `redis_db` if you would rather not use the default database number, which is set to `1`.

If you have a problem connecting to IPv6, try setting `redis_ip_family` to `6`.

If your database connection should be encrypted, use the `redis_tls_ca`, `redis_tls_key`, and `redis_tls_cert` configurations, or set `redis_tls_enable` to `true` if you don’t use a custom certificate.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--connecting-to-redis-cluster">

### Connecting to Redis Cluster

To set up a connection with a Redis Cluster, nodes need to be provided as the `REDIS_CLUSTER_NODES` variable.

```
REDIS_CLUSTER_NODES        - required (for Redis Cluster connection)
REDIS_IP_FAMILY            - optional (required only when using an IPv6 domain in `REDIS_CLUSTER_NODES`)

```

The `REDIS_CLUSTER_NODES` variable needs to contain a list of nodes in the dedicated format, which consists of:

```
"IP:PORT:[optional PASSWORD],IP:PORT:[optional PASSWORD]"

```

To understand the connection string format, check the examples below:

```
# IPv6
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000,[0:0:0:0:0:0:0:1]:7001,[0:0:0:0:0:0:0:1]:7002"

# IPv6 with a password
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000:password1,[0:0:0:0:0:0:0:1]:7001:password2,[0:0:0:0:0:0:0:1]:7002:password3"

# Domain name
REDIS_CLUSTER_NODES: "example.redis.server.com:7000,example.redis.server.com:7001,example.redis.server.com:7002"

# Domain name with IPv6 support
REDIS_IP_FAMILY: 6
REDIS_CLUSTER_NODES: "example.ipv6.redis.server.com:7000,example.ipv6.redis.server.com:7001,example.ipv6.redis.server.com:7002"

# Domain name with a password
REDIS_CLUSTER_NODES: "example.redis.server.com:7000:password1,example.redis.server.com:7001:password2,example.redis.server.com:7002:password3"

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--storage">

### Storage

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--s3-storage">

#### S3 storage

To configure S3 as your file storage, you should first set the `storage_driver` variable to `s3`.

Then, you can provide:

* `storage_access_key_id` and `storage_secret_access_key` to authorize the service.
* `storage_bucket` to set the bucket where the files should be stored.

If you use an S3-compatible server, you can set the address with the `storage_endpoint` variable.

```
STORAGE_DRIVER=s3
STORAGE_REGION=[AWS_REGION]
STORAGE_ACCESS_KEY_ID=[AWS_ACCESS_KEY_ID]
STORAGE_SECRET_ACCESS_KEY=[AWS_SECRET_ACCESS_KEY]
STORAGE_BUCKET=[AWS_S3_BUCKET]
STORAGE_ENDPOINT=[AWS_S3_ENDPOINT]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--azure-blob-storage">

#### Azure Blob Storage

To configure Azure Blob Storage as your file storage, you should first set the `storage_driver` variable to `azure`.

Then, you can provide:

* `storage_account_name` and `storage_account_key` authorize to the service.
* `storage_container` to set the container where the files should be stored.

```
STORAGE_DRIVER=azure
STORAGE_ACCOUNT_NAME=[AZURE_ACCOUNT_NAME]
STORAGE_ACCOUNT_KEY=[AZURE_ACCOUNT_KEY]
STORAGE_CONTAINER=[AZURE_CONTAINER]
STORAGE_ENDPOINT=[AZURE_ENDPOINT]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--filesystem">

#### Filesystem

To configure the filesystem as your file storage, you should first set the `storage_driver` variable to `filesystem`.

Then you can provide the path to the directory where the files should be stored using the `storage_location` variable.

```
STORAGE_DRIVER=filesystem
STORAGE_LOCATION=/var/storage/location

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--sql-storage">

#### SQL storage

To configure MySQL or Postgres as your file storage, you should set the `storage_driver` variable to `database`. When using SQL as a storage driver, the application will use the configuration provided in the `database_*` variables.

```
STORAGE_DRIVER=database

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--llm-providers">

### LLM Providers

CKEditor AI On-Premises supports the following LLM model providers:

* OpenAI
* Anthropic
* Google (Gemini family models)
* Azure OpenAI
* Amazon Bedrock
* Google Vertex AI (Gemini and Anthropic models)
* Custom providers (OpenAI API compatible)

To configure a provider, you need to set the appropriate provider options in the `providers` variable.

For each provider type, you can set the following options:

* `type` (required) – the type of the provider (“openai”, “anthropic”, “google”, “azure”, “bedrock”, “vertex” or “openai-compatible”).
* `name` (optional) – the name of the provider to be displayed in the models list. If not provided, the service will default to the provider key.
* `baseUrl` (required for `openai-compatible` type, optional for other types) – the base URL of the provider. For `openai-compatible` providers, all LLM requests will be sent to the `{baseUrl}/chat/completions` endpoint. For other provider types, this overrides the default API URL.
* `headers` (optional) – additional headers sent with every request to the provider.
* `apiKeys` (optional for the `openai-compatible`, `bedrock`, and `vertex` types, required for other types) – the API keys for the provider.

The Azure provider has the following additional options:

* `resourceName` (optional) – the Azure resource name. You can also point to your Azure resource with `baseUrl`.
* `apiVersion` (optional) – a custom API version.

The Amazon Bedrock provider has the following additional options:

* `credentials` (optional) – IAM credentials. Use this instead of API keys when you prefer IAM-based authentication.  
  * `accessKeyId` (required) – the AWS access key ID.
  * `secretAccessKey` (required) – the AWS secret access key.
  * `sessionToken` (optional) – the AWS session token.

The Google Vertex AI provider has the following additional options:

* `project` (required) – the Google Cloud project ID.
* `location` (required) – the Google Cloud location (for example, a region such as `us-central1`).
* `credentials` (optional) – Google Cloud service account credentials. Use this instead of API keys when you prefer service account authentication.  
  * `clientEmail` (required) – the service account email.
  * `privateKey` (required) – the service account private key.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--custom-models">

#### Custom models

By default, we use the default list of available models for each provider. If you want to change the list of available models or set the appropriate models for your custom provider, you can do so by specifying the `models` variable.

For each model you can set the following options:

* `id` (required) – the ID of the model. It should be unique across all models. Used to specify the model in a call to the LLM provider.
* `provider` (required) – the id of model’s provider. It should be the same as the provider key in the `providers` variable.
* `description` (required) – the description of the model to be displayed in the models list.
* `name` (optional) – the name of the model to be displayed in the models list. If not provided, the model will be displayed with the model id.
* `recommended` (optional) – whether the model should be placed in the recommended models list (list of models used by default by CKE5)
* `capabilities` (optional) – the capabilities of the model. It should be an object with the following keys:

  * `webSearch` (optional, default: false) – whether the model can use the web search feature.
  * `reasoning` (optional, default: false) – whether the model can use the reasoning feature.
* `contextLimits` (optional) – the context limits of the model for single conversation. It should be an object with the following keys:

  * `maxContextLength` (optional, default: 256000) – max context length in number of characters.
  * `maxFiles` (optional, default: 100) – max number of files in a context.
  * `maxFileSize` (optional, default: 5 MB for Anthropic models or 7 MB for other models) – max file size for a single file in bytes.
  * `maxTotalFileSize` (optional, default: 30 MB) – max total file size for all files in a context in bytes.
  * `maxTotalPdfFilePages` (optional, default: 100) – max total number of pages for all PDF files in a context.
* `features` (optional) – the list of the features that the model should be used for. Users cannot set the model for each feature by themselves in our service. For example, system reviews, system quick actions, and conversation title generation use models defined by our service. This option allows you to specify which features the model should be used for. You can set the same feature to multiple models – models will be sorted and used in the order of appearance in your configuration.  
Available features:

  * `conversations` – the model can be used for all conversations-related features.
  * `conversations.titleGeneration` – the model can be used for conversation title generation.
  * `reviews` – the model can be used for all reviews.
  * `reviews.correctness` – the model can be used for a correctness review.
  * `reviews.clarity` – the model can be used for a clarity review.
  * `reviews.readability` – the model can be used for a readability review.
  * `reviews.make-longer` – the model can be used for making text longer review.
  * `reviews.make-shorter` – the model can be used for making text shorter review.
  * `reviews.make-tone-casual` – the model can be used for making text more casual review.
  * `reviews.make-tone-direct` – the model can be used for making text more direct review.
  * `reviews.make-tone-friendly` – the model can be used for making text more friendly review.
  * `reviews.make-tone-confident` – the model can be used for making text more confident review.
  * `reviews.make-tone-professional` – the model can be used for making text more professional review.
  * `reviews.translate` – the model can be used for a translation review.
  * `actions` – the model can be used for all actions.
  * `actions.make-longer` – the model can be used for making text longer.
  * `actions.make-shorter` – the model can be used for making text shorter.
  * `actions.make-tone-casual` – the model can be used for making text more casual.
  * `actions.make-tone-direct` – the model can be used for making text more direct.
  * `actions.make-tone-friendly` – the model can be used for making text more friendly.
  * `actions.make-tone-confident` – the model can be used for making text more confident.
  * `actions.make-tone-professional` – the model can be used for making text more professional.
  * `actions.translate` – the model can be used for translation action.
  * `actions.continue` – the model can be used for the continue action.
  * `actions.fix-grammar` – the model can be used to fix grammar.
  * `actions.improve-writing` – the model can be used to improve writing.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--opentelemetry">

### OpenTelemetry

CKEditor AI On-Premises supports OpenTelemetry instrumentation for monitoring AI interactions, token usage, HTTP requests, and database operations. OpenTelemetry is enabled by setting `LLM_TELEMETRY_ENABLED` to `true` and providing the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` variable.

```
LLM_TELEMETRY_ENABLED=[true|false]
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=[OTLP_TRACES_ENDPOINT_URL]
OTEL_TRACES_SAMPLER_ARG=[SAMPLING_RATE]
OTEL_DEBUG=[true|false]

```

Additionally, you can enable native [Langfuse](https://langfuse.com/) integration for AI-specific observability by providing Langfuse API keys:

```
LANGFUSE_PUBLIC_KEY=[YOUR_LANGFUSE_PUBLIC_KEY]
LANGFUSE_SECRET_KEY=[YOUR_LANGFUSE_SECRET_KEY]
LANGFUSE_BASE_URL=[LANGFUSE_URL]
LANGFUSE_DEBUG=[true|false]

```

For detailed setup instructions, a full list of collected telemetry data, and configuration examples, refer to the [Observability](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html) guide.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--scraping-web-resources">

### Scraping web resources

To configure a custom endpoint for web scraping, define the following variables:

* `webresources_enabled` – must be set to `true`.
* `webresources_endpoint` – the endpoint URL of your custom gateway for downloading web resources.
* `webresources_request_timeout` – maximum request timeout in milliseconds (optional).

```
WEBRESOURCES_ENABLED="true"
WEBRESOURCES_ENDPOINT=[WEBRESOURCES_ENDPOINT]
WEBRESOURCES_REQUEST_TIMEOUT=[WEBRESOURCES_REQUEST_TIMEOUT]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--request-format">

#### Request format

Your custom endpoint should accept POST requests with the following JSON body:

```
{
  "url": "https://example.com/page-to-scrape"
}

```

Where:

* `url` (required) – the URL of the page to scrape.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--response-format">

#### Response format

Your endpoint should return a successful response in the following format:

```
{
  "type": "text/html",
  "data": "<html>...</html>"
}

```

Where:

* `type` (required) – the content type of the scraped data. Allowed values: `text/html`, `text/markdown`.
* `data` (required) – the scraped website content.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--using-web-search">

### Using web search

To configure a custom endpoint for web search, define the following variables:

* `websearch_enabled` – must be set to `true`.
* `websearch_endpoint` – the endpoint URL of your custom gateway for performing web searches.
* `websearch_request_timeout` – maximum request timeout in milliseconds (optional).
* `websearch_headers` – additional headers sent with every web search request. It can be defined as a JSON object or a string in the format `key1:value1,key2:value2...` (optional).

```
WEBSEARCH_ENABLED="true"
WEBSEARCH_ENDPOINT=[WEBSEARCH_ENDPOINT]
WEBSEARCH_REQUEST_TIMEOUT=[WEBSEARCH_REQUEST_TIMEOUT]
WEBSEARCH_HEADERS=[WEBSEARCH_HEADERS]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--request-format-2">

#### Request format

Your custom endpoint should accept POST requests with the following JSON body:

```
{
  "query": "search query string"
}

```

Where:

* `query` (required) – the search query string.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--response-format-2">

#### Response format

Your endpoint should return a successful response in the following format:

```
{
  "results": [
    {
      "url": "https://example.com/article",
      "text": "A snippet or excerpt of the content",
      "title": "Article Title",
      "author": "Author Name",
      "publishedAt": "2024-12-12T10:30:00Z",
      "favicon": "https://example.com/favicon.ico"
    }
  ]
}

```

Where:

* `results` (required) – an array of web search results.

Each result object contains:

* `url` (required) – the URL of the search result.
* `text` (required) – a snippet or excerpt of the content.
* `title` (optional) – the title of the search result.
* `author` (optional) – the author of the content.
* `publishedAt` (optional) – the publication date and time of the content in ISO 8601 format.
* `favicon` (optional) – the URL of the favicon for the website.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html"</a>

## Deployment

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--infrastructure">

### Infrastructure

To run CKEditor AI on your server, you need to have certain services prepared first:

* An SQL database (MySQL and Postgres are supported)
* A Redis database
* Data storage (S3, Azure Blob Storage, filesystem, MySQL, or Postgres)

Besides, you need an Open Container runtime to run CKEditor AI. You can use, among others: Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances.

We also recommend using a load balancer. You can use almost any load balancer you choose, like NGINX, HAProxy, Amazon Elastic Load Balancing, or Azure Load Balancer. Thanks to this, you will be able to create TLS connections and run several cooperating instances of CKEditor AI On-Premises. It will increase the security and the performance of the application.

For a detailed description of the recommended infrastructure, see the [Architecture](#cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html) guide.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--sql-database">

#### SQL Database

The SQL database stores persistent data like configurations, conversations, files and documents. It can also be used as a data storage for your files.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--mysql">

##### MySQL

The minimum required version of MySQL is 8.0\. The database and user should have at least the following privileges: `ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, TRIGGER, UPDATE, LOCK TABLES, REFERENCES`.

The database should be created before running CKEditor AI On-Premises. An example database creation script:

```
CREATE DATABASE `ai-service-on-premises`
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_bin;

```

If you want to use another SQL database like Microsoft SQL Server, etc., please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--postgresql">

##### PostgreSQL

The minimum required version of PostgreSQL is 12.0\. The database and user should have at least the following privileges: `SELECT, INSERT, UPDATE, DELETE, REFERENCES, CREATE, USAGE`.

The database with a schema should be created before running CKEditor AI On-Premises. An example database and schema creation script:

```
CREATE DATABASE "cksource";
\connect "cksource";
CREATE SCHEMA "ai-service-on-premises";

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--integration-with-collaboration-server-on-premises">

### Integration with Collaboration Server On-Premises

CKEditor AI On-Premises can be integrated with [Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/overview.html) so that both services share a single infrastructure. This means both services connect to **the same SQL database instance and the same Redis instance** — you do not need separate databases for AI and collaboration.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--prerequisites">

#### Prerequisites

Before integrating, make sure you have a working Collaboration Server On-Premises deployment. Refer to the [Collaboration Server Quick Start](#cs/latest/onpremises/cs-onpremises/installation/quickstart.html) or the [Collaboration Server Architecture](#cs/latest/onpremises/cs-onpremises/architecture.html) guide for setup details.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--configuration">

#### Configuration

To integrate, configure CKEditor AI On-Premises with the same `DATABASE_*` and `REDIS_*` environment variables that your Collaboration Server uses. Both services must point to the same database and Redis hosts:

```
docker run --init -p 8000:8000 \
    -e LICENSE_KEY=[your license key] \
    -e DATABASE_DRIVER=[mysql|postgres] \
    -e DATABASE_HOST=[same host as Collaboration Server] \
    -e DATABASE_USER=[same user as Collaboration Server] \
    -e DATABASE_PASSWORD=[same password as Collaboration Server] \
    -e DATABASE_DATABASE=[same database as Collaboration Server] \
    -e REDIS_HOST=[same Redis host as Collaboration Server] \
    -e PROVIDERS='{"openai":{"type":"openai","apiKeys":["your-api-key"]}}' \
    -e STORAGE_DRIVER=[s3|azure|filesystem|database] \
    docker.cke-cs.com/ai-service:[version]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--what-changes-when-integrated">

#### What changes when integrated

* **Shared environments** – All environments and access keys created in the Collaboration Server [Management Panel](#cs/latest/onpremises/cs-onpremises/management.html) become available to CKEditor AI On-Premises automatically.
* **Single management panel** – The AI-specific Management Panel is disabled. All configuration for both services is handled through the Collaboration Server Management Panel.
* **Shared data layer** – Both services read from and write to the same SQL database and Redis instance. You do not create a separate database for AI.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--token-endpoint-for-collaboration-and-ai">

#### Token endpoint for collaboration and AI

When using both collaboration and AI features, the JWT token should include permissions for both services. Include `auth.collaboration` for collaboration roles and `auth.ai.permissions` for AI access in the same token payload:

```
{
    "aud": "your-environment-id",
    "sub": "user-123",
    "auth": {
        "collaboration": {
            "*": {
                "role": "writer"
            }
        },
        "ai": {
            "permissions": [
                "ai:conversations:*",
                "ai:models:agent",
                "ai:actions:system:*",
                "ai:reviews:system:*"
            ]
        }
    }
}

```

For more details, see the [Token endpoint guide](#cs/latest/developer-resources/security/token-endpoint.html) (including the [combined example](#cs/latest/developer-resources/security/token-endpoint.html--example-token-payload-for-collaboration-and-ai)) and the [CKEditor AI Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--running-the-service">

### Running the service

After meeting all infrastructure requirements, you can prepare the CKEditor AI application to run. Follow the steps below to install CKEditor AI On-Premises using the Docker image.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-1-get-your-download-token">

#### Step 1: Get your Download token

To pull the CKEditor AI On-Premises Docker image, you need a download token.

1. Log in to the [Customer Portal](https://portal.ckeditor.com/).
2. Navigate to **Subscription → License keys → CKEditor AI Server**.
3. Scroll to the **Download tokens** section.
4. If no tokens exist, click **Create token**.
5. Copy and save the token.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-2-pull-the-docker-image">

#### Step 2: Pull the Docker image

Use the download token to log into the CKEditor AI On-Premises Docker Registry and pull the image:

```
docker login -u ai-service -p [DOWNLOAD_TOKEN] https://docker.cke-cs.com
docker pull docker.cke-cs.com/ai-service:latest

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-3-launch-the-docker-container">

#### Step 3: Launch the Docker container

Start the container with the required environment variables. You can use the [Setup wizard](#cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html) to generate a command tailored to your infrastructure, or use the example below as a starting point. All available options are described in the [Configuration section](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html).

```
docker run --init -p 8000:8000 \
    -e LICENSE_KEY=[your license key from Customer Portal] \
    -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your management secret key used in management panel] \
    -e DATABASE_DRIVER=[mysql|postgres] \
    -e DATABASE_HOST=[your database host] \
    -e DATABASE_USER=[your database user] \
    -e DATABASE_PASSWORD=[your database user password] \
    -e DATABASE_DATABASE=[your database name] \
    -e REDIS_HOST=[your redis host] \
    -e PROVIDERS='{"openai":{"type":"openai","apiKeys":["your-api-key"]}}' \
    -e STORAGE_DRIVER=[s3|azure|filesystem|database] \
    -e STORAGE_ACCESS_KEY_ID=[your AWS access key] \
    -e STORAGE_SECRET_ACCESS_KEY=[your AWS secret key] \
    -e STORAGE_BUCKET=[your S3 bucket name] \
    docker.cke-cs.com/ai-service:[version]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-4-create-an-environment-and-access-key">

#### Step 4: Create an Environment and Access Key

1. Open the Management Panel in your browser. The panel is available at the address where your CKEditor AI On-Premises instance is running (e.g. `http://localhost:8000`).
2. Enter the `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` you provided to the container.
3. Create a new **Environment**.
4. Inside the environment, create a new **Access Key**.
5. Save both the `Environment ID` and the `Access Key` — you will need them for the token endpoint.

For more details on managing environments and access keys, see the [Access Key guide](#cs/latest/developer-resources/security/access-key.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-5-create-the-token-endpoint">

#### Step 5: Create the token endpoint

Use the `Environment ID` and `Access Key` from the previous step to create a [token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) in your application. The token endpoint generates JWT tokens that authorize your users to use CKEditor AI features.

Make sure the token includes `auth.ai.permissions` to grant access to AI features. See the [Node.js token endpoint example](#cs/latest/examples/token-endpoints/nodejs.html) (including the CKEditor AI section) for a ready-to-use implementation, or check examples in [PHP](#cs/latest/examples/token-endpoints/php.html), [Python](#cs/latest/examples/token-endpoints/python.html), [Java](#cs/latest/examples/token-endpoints/java.html), and [ASP.NET](#cs/latest/examples/token-endpoints/dotnet.html).

For details on AI-specific permissions, see the [CKEditor AI Permissions guide](#cs/latest/guides/ckeditor-ai/permissions.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/index.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/index.html"</a>

## CKEditor AI On-Premises

The On-Premises version of CKEditor AI is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKEditor AI available as SaaS.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html) – An introduction to CKEditor AI On-Premises.
* [Quick-start checklist](#cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html) – Track your setup progress with an interactive checklist.
* [Setup wizard](#cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html) – Generate a ready-to-use configuration command.
* [Architecture](#cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html) – Learn about the recommended infrastructure for CKEditor AI On-Premises.
* [Deployment](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html) – Learn how to install CKEditor AI On-Premises.
* [API](#cs/latest/onpremises/ckeditor-ai-onpremises/api.html) – Learn how to use the CKEditor AI On-Premises REST API.
* [Configuration](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html) – Learn how to configure CKEditor AI On-Premises.
* [SSL communication](#cs/latest/onpremises/ckeditor-ai-onpremises/ssl.html) – Learn how to set up secure communication with CKEditor AI On-Premises.
* [Observability](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html) – Learn how to monitor AI interactions, token usage, and service health using OpenTelemetry.
* [Logs](#cs/latest/onpremises/ckeditor-ai-onpremises/logs.html) – Learn how to manage the logs of CKEditor AI On-Premises.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/logs.html"</a>

## CKEditor AI On-Premises logs

The logs from CKEditor AI On-Premises are written to `stdout` and `stderr`. Most of them are formatted in JSON. They can be used for monitoring or debugging purposes. In production environments, we recommend storing the logs to files or using a distributed logging system (like ELK or CloudWatch).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--monitoring-ckeditor-ai-with-logs">

### Monitoring CKEditor AI with logs

To get more insight into how the CKEditor AI On-Premises is performing, we built logs that can be used for monitoring. To enable these, just add the `ENABLE_METRIC_LOGS=true` environment variable.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--log-structure">

#### Log structure

The log structure contains the following information:

* `handler` – A unified identifier of action. Use this field to identify calls.
* `traceId` – A unique RPC call ID.
* `tags` – A semicolon-separated list of tags. Use this field to filter metrics logs.
* `data` – An object containing additional information. It might vary between different transports.
* `data.duration` – The request duration in milliseconds.
* `data.transport` – The type of the request transport. It could be `http` or `ws` (websocket).
* `data.status` – The request status. It can be equal to `success`, `fail`, or `warning`.
* `data.statusCode` – The response status in the HTTP status code standard.

Additionally, for the HTTP transport, the following information is included:

* `data.url` – The URL path.
* `data.method` – The request method.

In case of an error, `data.status` will be equal to `failed` and `data.message` will contain the error message.

An example log for HTTP transport:

```
{
    "level": 30,
    "time": "2021-03-09T11:15:09.154Z",
    "msg": "Request summary",
    "handler": "ai-service",
    "traceId": "85f13d92-57df-4b3b-98bb-0ca41a5ae601",
    "data": {
        "duration": 2470,
        "transport": "http",
        "statusCode": 200,
        "status": "success",
        "url": "/assets",
        "method": "POST"
    },
    "tags": "metrics"
}

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--docker">

### Docker

Docker has a built-in logging mechanisms that capture logs from the containers’ output. The default logging driver writes these logs to files.

When using this driver, you can use the `docker logs` command to show logs from a container. You can add the `-f` flag to view logs in real time. Refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/logs/) for more information about the `logs` command.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--distributed-logging">

### Distributed logging

If you are running more than one instance of CKEditor AI On-Premises, we recommend using a distributed logging system. It allows you to view and analyze logs from all instances in one place.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--aws-cloudwatch-and-other-cloud-solutions">

#### AWS CloudWatch and other cloud solutions

If you are running CKEditor AI On-Premises in the cloud, the simplest and recommended way is to use a service that is available from your selected provider. Here are some of the available services:

* AWS – [CloudWatch](https://aws.amazon.com/CloudWatch)
* Google Cloud – [Cloud Logging](https://cloud.google.com/logging)
* Azure – [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/)

To use CloudWatch with AWS ECS, you have to create a log group first and change the log driver to `awslogs`. When the log driver is configured properly, logs will be streamed directly to CloudWatch.

The `logConfiguration` may look similar to this:

```
"logConfiguration": {
    "logDriver": "awslogs",
    "options": {
        "awslogs-region": "us-west-2",
        "awslogs-group": "cksource",
        "awslogs-stream-prefix": "ck-ai-service-logs"
    }
}

```

Refer to the [Using the awslogs Log Driver](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using%5Fawslogs.html) article for more information.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--on-premises-solutions">

#### On-Premises solutions

If you are using your own infrastructure or, for some reason, cannot use the service offered by your provider, you can always use some on-premises distributed logging system.

There are a lot of solutions available, including:

* [ELK](https://www.elastic.co/what-is/elk-stack) \+ [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html)  
This is a stack built on top of Elasticsearch, Logstash, and Kibana. In this configuration, Elasticsearch stores logs, Filebeat reads the logs from Docker and sends them to Elasticsearch, and Kibana is used to view them. Logstash is not necessary because the logs are already structured.
* [Fluentd](https://www.fluentd.org/)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/fluentd) to send the logs. It has a built-in frontend, but can also be integrated with Elasticsearch and Kibana for better filtering.
* [Graylog](https://www.graylog.org)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/gelf) to send the logs. It has a built-in frontend and needs Elasticsearch to store the logs as well as a MongoDB database to store the configuration.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/logs.html--example-configuration">

##### Example configuration

The example configuration uses Fluentd, Elasticsearch, and Kibana to capture logs from Docker.

Before running CKEditor AI On-Premises, you have to prepare the logging services. For this example, Docker Compose is used. Create the `fluentd`, `elasticsearch`, and `kibana` services inside the `docker-compose.yml` file:

```
version: '3.7'
services:
    fluentd:
        build: ./fluentd
        volumes:
            - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
        ports:
            - "24224:24224"
            - "24224:24224/udp"

    elasticsearch:
        image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
        expose:
            - 9200
        ports:
            - "9200:9200"

    kibana:
        image: docker.elastic.co/kibana/kibana:6.8.5
        environment:
            ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
        ports:
            - "5601:5601"

```

To integrate Fluentd with Elasticsearch, you first need to install `fluent-plugin-elasticsearch` in the Fluentd image. To do this, create a `fluentd/Dockerfile` with the following content:

```
FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
    && gem install fluent-plugin-elasticsearch \
    && gem sources --clear-all

```

Next, configure the input server and connection to Elasticsearch in the `fluentd/fluent.conf` file:

```
<source>
    @type forward
    port 24224
    bind 0.0.0.0
</source>
<match *.**>
    @type copy
    <store>
        @type elasticsearch
        host elasticsearch
        port 9200
        logstash_format true
        logstash_prefix fluentd
        logstash_dateformat %Y%m%d
        include_tag_key true
        type_name access_log
        tag_key @log_name
        flush_interval 1s
    </store>
    <store>
        @type stdout
    </store>
</match>

```

Now you are ready to run the services:

```
docker-compose up --build

```

When the services are ready, you can finally start CKEditor AI On-Premises.

```
docker run --init -p 8000:8000 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
docker.cke-cs.com/ai-service:[version]

```

Now open Kibana in your browser. It is available at <http://localhost:5601/>. In the first run, you may be asked about creating an index. Use the `fluentd-*` pattern and press the “Create” button. After this step, your logs should appear in the “Discover” tab.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html"</a>

## CKEditor AI On-Premises – MCP support

The On-Premises version of the CKEditor AI provides basic functionality for connecting to MCP servers using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--configuration">

### Configuration

To integrate an external MCP server, you need to supply the appropriate configuration for the MCP client.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--basic-setup">

#### Basic setup

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--http-headers">

#### HTTP headers

The configuration also supports specifying additional HTTP headers (e.g., an authorization token) that will be included with each request sent to the MCP server:

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--tools">

#### Tools

For some MCP servers, you may want to disable specific tools to prevent the LLM from making harmful or dangerous actions. You can do this by providing the names of the tools to disable in the `tools.disabled` array.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--additional-options">

#### Additional options

You can also configure additional options for the MCP client by providing them in the `options` object. Currently we support the following options:

* `callToolTimeout` (optional, default: 60 seconds) – the timeout for the MCP tool call in seconds.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html--usage">

### Usage

Once the MCP client is configured, it will automatically establish a connection to the MCP server and retrieve the list of available tools. These tools will then be accessible to AI models during conversations (not in reviews or quick actions), enabling them to determine when and how to use them as needed.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html"</a>

## Nightly releases

This article describes the purpose and usage of nightly releases of CKEditor AI On-Premises images.

Nightly images are released every day. During the automatic release, we run our tests to make sure that these images are working correctly, but unlike stable releases, nightly builds do not go through our full release process and are not tested and approved by our Quality Assurance.

Nightly images include all of the changes that are merged on our development branches. This allows you to access new features or receive fixes faster than with stable on-premises images.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html--dangers-of-using-nightly-builds">

### Dangers of using nightly builds

Nightly builds are released automatically. By the nature of these images, they should be treated as unstable. Running an On-Premises application using these images may result in some unexpected behaviors, undocumented features, or known and unknown defects.

You need to ensure that the versions that you are willing to run are working correctly and will not impact your application negatively. We highly recommend using DEV/UAT environments first and going through the process of quality acceptance on your side before you use nightly images in production.

By using the nightly builds, you accept the risks mentioned in the documentation.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html--nightly-images-usage">

### Nightly images usage

There is a difference between the usage of nightly and stable releases of CKEditor AI On-Premises. Instead of the `ai-service` image, you should use the `ai-service-nightly` images. Notice that the version of nightly images also includes a date and a hash. This date part can help you find the latest version of the nightly build. Example usage:

```
version: "2.2"
services:
    ai-service-nightly:
        image: docker.cke-cs.com/ai-service-nightly:5.0.0-20260227-a846c2137 # change the version
        ports:
        - "8000:8000"
        # environment variables and other configuration

```

Nightly builds are available only as Docker images.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html--list-of-available-nightly-versions">

### List of available nightly versions

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html--nightly-versions">

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/nightly-releases.html--fetching-the-latest-nightly-version">

### Fetching the latest nightly version

If you want to automate the process of updating your application and automatically use the latest versions of nightly builds, you can make a GET request at <https://docker.cke-cs.com/api/versions/ai-service-nightly>. This will fetch the JSON with all available versions. Use the date in the version to find the latest image that can be used in your application.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/observability.html"</a>

## CKEditor AI On-Premises – Observability

CKEditor AI On-Premises supports [OpenTelemetry](https://opentelemetry.io/) instrumentation, giving you full visibility into the service’s runtime behavior. This includes AI interactions with LLM providers, token usage, response quality, as well as HTTP requests and database operations.

Telemetry data can be exported to any OTLP-compatible backend (such as Jaeger, Grafana Tempo, or Datadog) and, optionally, to [Langfuse](https://langfuse.com/) for AI-specific observability. Both exports can run simultaneously.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--configuration">

### Configuration

OpenTelemetry is enabled by setting `LLM_TELEMETRY_ENABLED` to `true` and providing the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable. When both are configured, the service starts collecting and exporting trace data.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--otlp-exporter">

#### OTLP exporter

The following environment variables control the OTLP trace export:

```
LLM_TELEMETRY_ENABLED=[true|false]
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=[OTLP_TRACES_ENDPOINT_URL]
OTEL_TRACES_SAMPLER_ARG=[SAMPLING_RATE]
OTEL_DEBUG=[true|false]

```

Where:

* `LLM_TELEMETRY_ENABLED` (required, default: `false`) – set to `true` to enable LLM telemetry collection. Without this, no telemetry data is collected or exported.
* `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (required) – the URL of the OTLP-compatible endpoint to send trace data to (for example, `http://jaeger:4318/v1/traces`).
* `OTEL_TRACES_SAMPLER_ARG` (optional, default: `1.0`) – the sampling rate as a float between `0.0` and `1.0`. A value of `1.0` means all traces are captured, `0.5` means roughly half, and so on. Lowering the sampling rate reduces the volume of exported data in high-traffic environments.
* `OTEL_DEBUG` (optional) – when set to any truthy value, enables verbose OpenTelemetry diagnostic logging to `stdout`. Useful for troubleshooting OTLP export issues.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--langfuse">

#### Langfuse

[Langfuse](https://langfuse.com/) is an open-source LLM observability platform that provides detailed dashboards for monitoring AI interactions, token usage, costs, and response quality. CKEditor AI On-Premises integrates with Langfuse natively through a dedicated span processor.

Langfuse integration is enabled when both `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set:

```
LANGFUSE_PUBLIC_KEY=[YOUR_LANGFUSE_PUBLIC_KEY]
LANGFUSE_SECRET_KEY=[YOUR_LANGFUSE_SECRET_KEY]
LANGFUSE_BASE_URL=[LANGFUSE_URL]
LANGFUSE_DEBUG=[true|false]

```

Where:

* `LANGFUSE_PUBLIC_KEY` (required) – the public API key from your Langfuse project.
* `LANGFUSE_SECRET_KEY` (required) – the secret API key from your Langfuse project.
* `LANGFUSE_BASE_URL` (optional, default: `https://cloud.langfuse.com`) – the base URL of your Langfuse instance. Override this when using a self-hosted Langfuse deployment.
* `LANGFUSE_DEBUG` (optional) – when set to any truthy value, enables verbose diagnostic logging for Langfuse trace export. Unlike `OTEL_DEBUG`, which covers the general OpenTelemetry pipeline, this option focuses specifically on the Langfuse span processor.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--using-otlp-and-langfuse-together">

#### Using OTLP and Langfuse together

The OTLP exporter and Langfuse span processor run as independent export pipelines. This means you can:

* Use **only OTLP** – to send all traces to a general-purpose backend like Jaeger or Grafana Tempo.
* Use **OTLP with Langfuse** – to get both infrastructure-level tracing and AI-specific insights in Langfuse simultaneously.

When both are configured, traces are sent to both destinations in parallel.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--docker-example">

### Docker example

Below is an example of running CKEditor AI On-Premises with OpenTelemetry enabled and connected to Langfuse Cloud:

```
docker run --init -p 8000:8000 \
    -e LICENSE_KEY=[your license key] \
    -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your management secret key] \
    -e DATABASE_DRIVER=[mysql|postgres] \
    -e DATABASE_HOST=[your database host] \
    -e DATABASE_USER=[your database user] \
    -e DATABASE_PASSWORD=[your database password] \
    -e DATABASE_DATABASE=[your database name] \
    -e REDIS_HOST=[your redis host] \
    -e PROVIDERS='{"openai":{"type":"openai","apiKeys":["your-api-key"]}}' \
    -e STORAGE_DRIVER=[s3|azure|filesystem|database] \
    -e LLM_TELEMETRY_ENABLED="true" \
    -e OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://your-otlp-collector:4318/v1/traces" \
    -e LANGFUSE_PUBLIC_KEY="pk-lf-..." \
    -e LANGFUSE_SECRET_KEY="sk-lf-..." \
    docker.cke-cs.com/ai-service:[version]

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/observability.html--environment-variables-reference">

### Environment variables reference

| Variable                               | Required | Default                    | Description                                                   |
| -------------------------------------- | -------- | -------------------------- | ------------------------------------------------------------- |
| LLM\_TELEMETRY\_ENABLED                | Yes      | false                      | Enables LLM telemetry collection. Must be set to true.        |
| OTEL\_EXPORTER\_OTLP\_TRACES\_ENDPOINT | Yes      | –                          | OTLP endpoint URL for trace export.                           |
| OTEL\_TRACES\_SAMPLER\_ARG             | No       | 1.0                        | Trace sampling rate (0.0–1.0).                                |
| OTEL\_DEBUG                            | No       | –                          | Enables verbose OpenTelemetry diagnostic logging.             |
| LANGFUSE\_PUBLIC\_KEY                  | No       | –                          | Langfuse public API key. Required for Langfuse integration.   |
| LANGFUSE\_SECRET\_KEY                  | No       | –                          | Langfuse secret API key. Required for Langfuse integration.   |
| LANGFUSE\_BASE\_URL                    | No       | https://cloud.langfuse.com | Base URL of the Langfuse instance.                            |
| LANGFUSE\_DEBUG                        | No       | –                          | Enables verbose diagnostic logging for Langfuse trace export. |

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/overview.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/overview.html"</a>

## CKEditor AI On-Premises – Overview

CKEditor AI On-Premises is a backend service for the [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html) feature that you can run in your own infrastructure, including private cloud deployments. CKEditor 5 connects to this service to provide in-editor AI assistance (AI Chat, AI Quick Actions, AI Review).

This distribution is intended for deployments that require control over where the service runs and how it connects (for example, private networking and outbound network access). It also supports organizations that want to operate the service using existing platform standards and processes, such as container-based deployment, scaling, monitoring, backups, and change management.

The CKEditor AI On-Premises installation requires two servers: one for running the application (the “Application Server”) and another one for hosting the databases (the “Database Server”).

The CKEditor AI On-Premises is distributed as a Docker Image. It can be used with any Open Container runtime, like Docker, Kubernetes, Amazon Elastic Container Service, or Azure Container Instances.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/overview.html--next-steps">

### Next steps

* [Quick-start checklist](#cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html) – Track your setup progress step by step.
* [Setup wizard](#cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html) – Generate a ready-to-use `docker run` command for your deployment.
* [Learn about the recommended architecture](#cs/latest/onpremises/ckeditor-ai-onpremises/architecture.html) for running CKEditor AI On-Premises.
* [Learn how to deploy CKEditor AI On-Premises](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html"</a>

## Quick-start checklist

Use this interactive checklist to track your progress while setting up CKEditor AI On-Premises. Your progress is saved in the browser automatically.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html--checklist">

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html--checklist-progress-fill"> 

0 / 9 completed 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html--infrastructure">

#### Infrastructure

**Prepare an SQL database** — Create a MySQL 8+ or PostgreSQL 12+ database. See the [database setup scripts](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--sql-database). **Prepare a Redis instance** — Redis 3.2.6 or newer. See [Redis configuration](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--redis-database). **Choose and configure file storage** — S3, Azure Blob Storage, filesystem, or SQL. See [Storage configuration](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--storage). 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html--installation">

#### Installation

**Get a Download token** — From the [Customer Portal](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-1-get-your-download-token). **Pull the Docker image** — Log in to the registry and pull the image. See [Step 2](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-2-pull-the-docker-image). **Configure LLM provider(s)** — Set up at least one provider (OpenAI, Anthropic, Google, Azure, Bedrock, Vertex, or custom). See [LLM Providers](#cs/latest/onpremises/ckeditor-ai-onpremises/configuration.html--llm-providers). **Launch the Docker container** — Start the service with environment variables. See [Step 3](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-3-launch-the-docker-container) or use the [Setup wizard](#cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html) to generate the command. **Create an Environment and Access Key** — Open the Management Panel and set up credentials. See [Step 4](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-4-create-an-environment-and-access-key). **Create a token endpoint** — Implement a JWT token endpoint in your application. See [Step 5](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-5-create-the-token-endpoint) and the [Node.js example](#cs/latest/examples/token-endpoints/nodejs.html). 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/quickstart-checklist.html--optional">

#### Optional

**Integrate with Collaboration Server** — Share database and Redis with Collaboration Server On-Premises. See [Integration guide](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--integration-with-collaboration-server-on-premises). **Configure MCP servers** — Connect external tool servers. See the [MCP guide](#cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html). **Set up Observability** — Enable OpenTelemetry and/or Langfuse. See the [Observability guide](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html"</a>

## Requirements

This article describes the requirements necessary for CKEditor AI On-Premises to run smoothly.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--ckeditor-ai-on-premises">

### CKEditor AI On-Premises

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--hardware-requirements">

#### Hardware requirements

It is impossible to provide a single infrastructure setup, that will fit all use cases. In this section, we provide recommendations for ensuring high availability and high performance of CKEditor AI On-Premises. As every use case is different, you need to monitor your application and adjust the infrastructure to your needs.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--high-availability">

##### High availability

To ensure high availability, we recommend running at least 3 instances of CKEditor AI On-Premises.

CKEditor AI On-Premises can be scaled with Docker containers on a single host machine. However, we recommend scaling on at least three host machines to provide the reliability of the system.

A load balancer, like HAProxy or NGINX (see the load balancer configuration examples in the [Reverse proxy](#cs/latest/onpremises/cs-onpremises/reverse-proxy.html) guide), is required for scaling on several machines. Of course, it is possible to use any cloud provider for scaling, such as Amazon ECS, Azure Container Instances, or Kubernetes.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--software-requirements">

#### Software requirements

Currently, we only provide Linux-based Docker images for CKEditor AI. We highly recommend running these on machines with Linux. However, you can also use Docker Desktop to run our Docker images on other operating systems.

The application is provided as a Docker image by default.

It can be run with any Open Container runtime tool, for example: [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

In the case of Windows machines, you need to enable the [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/about#what-is-wsl-2) backend and switch to Linux containers. Make sure that your operating system supports such an option. Refer to the [Docker Desktop installation guide](https://docs.docker.com/desktop/windows/install/) for more information.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--llm-providers">

### LLM Providers

CKEditor AI On-Premises currently supports three major LLM providers: OpenAI, Google (Gemini models), and Anthropic. We do not require the use of all of them, but at least one of them must be configured to ensure the service’s operability. To ensure optimal efficiency, we recommend utilizing all providers.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--sql-database">

### SQL Database

CKEditor AI On-Premises requires MySQL database in version 8.0 or Postgres PostgreSQL 12.0.  
If you want to use another SQL database like Microsoft SQL Server, etc., please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--containers">

#### Containers

Databases can be launched as containers, but this requires high awareness and responsiveness. Because each company has different policies and arrangements, we do not recommend any approach and leave the decision as to how the databases will be launched to you.

However, we encourage you to read this article: [“To run or not to run a database on Kubernetes: What to consider”](https://cloud.google.com/blog/products/databases/to-run-or-not-to-run-a-database-on-kubernetes-what-to-consider) before making a decision.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--redis">

### Redis

The required Redis version for CKEditor AI On-Premises is 3.2.6 or newer. CKEditor AI supports connection to a single instance Redis or Redis Cluster. Redis Sentinel is not supported.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/requirements.html--storage-system">

### Storage system

Storage systems that can be used with CKEditor AI On-Premises are:

* AWS S3,
* Azure Blob Storage,
* Filesystem,
* SQL databases (the largest file you can send using SQL database is 4GB).

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html"</a>

## Setup wizard

Use this interactive wizard to generate a `docker run` command tailored to your CKEditor AI On-Premises deployment. Select the options that match your infrastructure and copy the result.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--setup-wizard">

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--step-1-deployment-mode">

### Step 1: Deployment mode

Standalone AI Run CKEditor AI On-Premises as an independent service. AI + Collaboration Server Integrate with [Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/overview.html) using a shared database and Redis. 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--step-2-database">

### Step 2: Database

MySQL 8+ PostgreSQL 12+ 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--step-3-file-storage">

### Step 3: File storage

Amazon S3 Azure Blob Storage Filesystem SQL database 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--step-4-llm-provider">

### Step 4: LLM provider

Select one or more providers. You can configure additional providers later.

OpenAI Anthropic Google (Gemini) Azure OpenAI Amazon Bedrock Google Vertex AI Custom (OpenAI-compatible) 

Please select at least one provider.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--step-5-optional-features">

### Step 5: Optional features

MCP support Connect to external MCP servers. See the [MCP guide](#cs/latest/onpremises/ckeditor-ai-onpremises/mcp.html). OpenTelemetry Export traces to an OTLP-compatible backend. See the [Observability guide](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html). Langfuse AI-specific observability with Langfuse. See the [Observability guide](#cs/latest/onpremises/ckeditor-ai-onpremises/observability.html). 

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--result">

### Result

Copy the generated command and adjust the placeholder values (shown in square brackets) to match your environment.

docker run 

```bash

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/setup-wizard.html--next-steps">

#### Next steps

Once the container is running:

1. [Create an Environment and Access Key](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-4-create-an-environment-and-access-key) in the Management Panel.
2. [Create a token endpoint](#cs/latest/onpremises/ckeditor-ai-onpremises/deployment.html--step-5-create-the-token-endpoint) to authenticate your users. See the [Node.js example](#cs/latest/examples/token-endpoints/nodejs.html) for a ready-to-use implementation.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/ssl.html">source file: "cs/latest/onpremises/ckeditor-ai-onpremises/ssl.html"</a>

## CKEditor AI On-Premises SSL communication

You can communicate with the CKEditor AI On-Premises using secure connections. To achieve this, you need to set up a load balancer like `NGINX` or `HAProxy` with your SSL certificate.

You can find the `HAProxy` and `NGINX` configuration examples below.

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/ssl.html--haproxy-example">

### `HAProxy` example

Here is a basic `HAProxy` configuration:

```
global
    daemon
    maxconn 256
    tune.ssl.default-dh-param 2048

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/your_certificate.pem
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
    redirect scheme https if !{ ssl_fc }

    default_backend servers

backend servers
    server server1 127.0.0.1:8000 maxconn 32

```

<a id="cs/latest/onpremises/ckeditor-ai-onpremises/ssl.html--nginx-example">

### `NGINX` example

Here is a basic `NGINX` configuration:

```
events {
    worker_connections  1024;
}

http {
    server {
        server_name your.domain.name;

        listen 443;
        ssl on;
        ssl_certificate /etc/ssl/your_cert.crt;
        ssl_certificate_key /etc/ssl/your_cert_key.key;

        location / {
            proxy_pass http://127.0.0.1:8000;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
        }
    }
}

```

<a id="cs/latest/onpremises/cs-onpremises/architecture.html">source file: "cs/latest/onpremises/cs-onpremises/architecture.html"</a>

## Architecture

This article describes the recommended architecture for infrastructure that should be prepared for Collaboration Server On-Premises to run smoothly.

<a id="cs/latest/onpremises/cs-onpremises/architecture.html--overview">

### Overview

At the infrastructure level, two layers can be distinguished. The first is an [application layer](#cs/latest/onpremises/cs-onpremises/architecture.html--application-layer) which is used to run the application provided as a Docker image. The second layer is responsible for all data and it is a [database layer](#cs/latest/onpremises/cs-onpremises/architecture.html--database-layer). The application layer communicates with the database layer — any server running in the application layer can retrieve the data from the database layer.

This layered architecture is recommended for security reasons. The servers in the application layer are exposed to public access. However, the databases should be run in a separate layer, i.e. on separate servers, preferably in a different subnet to which external traffic will be limited. Access to databases should only be allowed for applications running in the [application layer](#cs/latest/onpremises/cs-onpremises/architecture.html--application-layer).

<a id="cs/latest/onpremises/cs-onpremises/architecture.html--application-layer">

### Application layer

The infrastructure in the application layer consists of application servers and a load balancer.

On each application server, it should be possible to run the application provided as a Docker image. To this end, it is recommended to use a containers orchestrator for clustering such as Docker Swarm, Kubernetes, etc. Thanks to this, it is possible to run and manage multiple instances of the application running on multiple application servers.

Due to the fact that all application data is stored in the [database layer](#cs/latest/onpremises/cs-onpremises/architecture.html--database-layer), it is possible that every request or socket connection can be redirected to other instances of the application. Thanks to this, in case of failure of one of the instances, the application will still be available for all users. To make this possible, it is necessary to run a load balancer in front of the application servers. The load balancer should be configured to redirect requests and connections to all application servers.

<a id="cs/latest/onpremises/cs-onpremises/architecture.html--database-layer">

### Database layer

The database layer consists of 2 databases.

The first of them, Redis, is used to store temporary data used in collaboration — the data is usually deleted after some time. This database is also used for scaling the application. Redis is needed for scaling because each user can connect to different instances of the application. In this case, a message delivered to one application instance via a WebSocket connection must be delivered to other instances of the application. By using this database, the application does not need to have knowledge of other application instances, because Redis handles the delivery of messages to all instances. Thanks to this behavior, no other complicated and difficult to start components are required.

The next database in the database layer is SQL (MySQL and PostgreSQL databases are currently supported). This database is used to save any data that must be saved permanently and is not needed only when a document is being edited, e.g. comments.

The application requires only providing the access data and server addresses on which the databases are located. Database requirements are available in the [Requirements](#cs/latest/onpremises/cs-onpremises/requirements.html--databases) section. Therefore, the databases can be run in any way — as a native installation on separate servers, using databases from any cloud providers or using Docker containers.

<a id="cs/latest/onpremises/cs-onpremises/architecture.html--examples">

### Examples

To aid our customers in building a stable and secure service, we created a set of ready-to-use IaC scripts to set up the Collaboration Server quicker. You can use this repository as a guide on how to build your own infrastructure with recommended configuration, employing the best practices. You can also deploy the Collaboration Server On-Premises to your infrastructure provider of choice with these few simple steps.

The script will initialize the infrastructure with multiple instances, set up the load balancer and the data layer. It will automatically fetch and run the application.

Check out these examples to learn more:

* [AWS ECS](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/aws/ecs)
* [Azure](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/azure/aks)

If you have any questions, feel free to [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/cs-onpremises/changelog.html">source file: "cs/latest/onpremises/cs-onpremises/changelog.html"</a>

## CKEditor Collaboration Server On-Premises

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--510-2026-04-14">

### 5.1.0 (2026-04-14)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features">

#### Features

* Added a new REST API endpoint to list uploaded editor bundles  
The new `GET /editors` REST API endpoint allows for listing all uploaded editor bundles.  
It lets you get a list of all uploaded editor bundles and their versions.  
You can find more information in the REST API documentation available  
under `/api/v5/docs#tag/Editor-bundles/paths/~1editors/get`.
* Added a new environment variable `SSE_API_WEBSOCKET_URL` to configure the WebSocket URL for the Server-Side Editors API  
Before, the Server Side Editor API was using the `APPLICATION_EXTERNAL_ENDPOINT` environment variable to connect to the Cloud Services server, now it can be configured using the `SSE_API_WEBSOCKET_URL` environment variable.  
The `APPLICATION_EXTERNAL_ENDPOINT` is still supported for backward compatibility.
* \[EXPERIMENTAL\] Added support for OpenTelemetry  
When the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable is set, the OpenTelemetry instrumentation is enabled so that traces are sent to the defined OTLP HTTP endpoint. You can set `OTEL_SERVICE_NAME` to identify the service in your telemetry backend, and optionally `OTEL_TRACES_SAMPLER_ARG` (defaults to `1.0`) to control the root trace sampling ratio.

**This integration is experimental; behavior and configuration may change in future releases.**

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes">

#### Fixes

* Fixed handling editor bundles with AI plugins  
Fixed an issue where editor bundles containing AI plugins were not handled correctly.  
The AI plugins are now properly excluded from the bundle processing on the server side.
* Fixed bundle caching  
Fixed an issue with the editor bundle caching mechanism that could cause stale bundles to be served.  
The issue could lead to an `Could not load script` error.  
The caching mechanism now correctly invalidates and refreshes the cached bundles.
* Fixed a potential content duplication issue during document loading  
Previously, a lack of locking during the document loading process could result in duplicated content  
in rare race condition scenarios. The loading process now correctly acquires a lock to prevent this issue.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes">

#### Other changes

* Improved the stability of the restore endpoint  
Previously, restoring a document could fail in certain edge cases.  
The restore endpoint has been improved to handle these cases correctly, providing better stability.
* Security improvements  
Applied security improvements to the Server-Side Editors API and the offline document conversion.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--500-2026-03-03">

### 5.0.0 (2026-03-03)

**Note:** The major version bump is due to the introduction of the compatibility with the CKEditor AI On-premises.  
From this version, both applications can be run on the same server.  
There are not any breaking changes in the Collaboration Server On-premises and the new release is fully compatible with the older versions.

It is highly recommended to synchronize the version of the CKEditor AI On-Premises with  
the CKEditor Collaboration Server On-Premises to ensure the compatibility of the two applications.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-2">

#### Features

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-2">

#### Other changes

* Improved performance and stability of collaboration features  
The way the editor bundle is run was improved, providing better performance and stability  
of features that rely on the backend document conversion.
* Updated Node to v24 LTS  
The Node version has been updated to v24 LTS to improve performance and security.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4262-2026-01-29">

### 4.26.2 (2026-01-29)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-3">

#### Other changes

* Added a possibility to skip SSL certificate verification for SSE API external requests  
Before, the SSE API external requests were blocked if the SSL certificate was not verified  
or if it was not trusted.  
To skip SSL certificate verification for SSE API external requests,  
the `ACCEPT_INSECURE_CERTS` environment variable must be set to `true`.  
It is disabled by default for security reasons.
* Improved performance of the adding new suggestions  
The locking mechanism used while adding new suggestions was replaced with a more efficient one.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4261-2025-12-08">

### 4.26.1 (2025-12-08)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-4">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4260-2025-12-02">

### 4.26.0 (2025-12-02)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-3">

#### Features

* Added the possibility to initialize a new collaboration session directly from the Document storage through the REST API  
Now the `/api/v5/{environment_id}/collaborations` method called without the `data` parameter will initialize  
a new collaboration session from the Document storage if the document is stored there.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration/paths/~1collaborations/post`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-2">

#### Fixes

* Fixed support for multi-root editors in the SSE API  
Fixed support for multi-root editors in Server-Side Editors API. The parameter `multi_root_configuration.roots_to_initialize`  
now allows specifying which roots should be initialized on the backend side.  
By default, the editor is initialized with the roots declared while uploading the editor bundle.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D~1evaluate-script/post`.
* Fixed a race condition while adding a suggestion with a parent suggestion  
Previously, in rare cases, a race condition could occur while adding a suggestion with a parent suggestion.  
The race condition could be visible when adding a suggestion while adding a link to a text in the document.  
The race condition could lead to the `Cannot find original suggestion` error.  
Now the race condition is fixed, and the suggestions are added correctly.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-5">

#### Other changes

* Added support for MySQL 8.4  
MySQL 8.4 is now supported as the database engine.  
When the database was created in a version older than 8.0, the database user must be manually upgraded  
to not use the deprecated `mysql_native_password` authentication plugin.  
The support for the plugin was dropped by the MySQL engine itself.  
The legacy user might be migrated to the `caching_sha2_password` authentication plugin.  
The migration process depends on the used infrastructure and database engine, so it is not possible  
to provide a generic solution.
* Added support for Valkey as the Redis alternative  
Valkey is a community-driven fork of Redis led by the Linux Foundation and supported by AWS and others.  
It might be used as an alternative to Redis; there are no additional steps required to use it.  
All authentication and configuration parameters are the same as for Redis.
* Increased the timeout for the SSE API to 60 seconds  
The increased timeout allows for more complex script executions and longer external requests.
* Lowered the log level of a message that is logged when an external request from the editor bundle fails  
The log level was lowered from `warn` to `debug` to not flood the logs.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4253-2025-10-14">

### 4.25.3 (2025-10-14)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-3">

#### Fixes

* Fixed document processing when relative paths to resources are used  
Documents that used relative paths in its content were failing while being processed by the editor bundle.  
Now, the relative paths are ignored and documents are processed correctly.
* Fixed support for AWS S3 Endpoint configuration in Easy Image  
Previously, the `STORAGE_ENDPOINT` environmental variable was not working properly when used with AWS S3.  
It could lead to errors resulting in an inability to upload or download images from Easy Image until the application restarts.  
Now the `STORAGE_ENDPOINT` environmental variable is supported when used with AWS S3.
* Fixed support for root attributes in a single-root editors  
Previously, the root attributes were not supported in a single-root editor, resulting in a attributes loss.  
Now, the root attributes are stored, decoded and returned correctly.
* Fixed issue with Environments API documentation  
Previously, the Environments API documentation page, contained only introduction and did not list  
any available endpoints.  
Now, the API correctly lists all available endpoints.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-6">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4252-2025-09-02">

### 4.25.2 (2025-09-02)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-4">

#### Fixes

* Fixed ghost sessions appearing after a quick connect-disconnect to a document  
After a quick connect-disconnect to a document, session was not terminated properly.  
Now, the session expires properly.
* Fixed Insights Panel’s filters in the Management Panel  
Previously, filtering the logs by level in the Management Panel was not working properly.  
Now, the logs are correctly filtered by level.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-7">

#### Other changes

* Added support for the `debug` mode in the Server-Side Editors API  
When developing and testing your editor scripts, you can enable the debug mode by setting the `debug: true` parameter in your API request.  
This will allow you to collect the `console.debug` logs from the script execution.  
It can be helpful for troubleshooting and understanding script behavior.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4251-2025-08-14">

### 4.25.1 (2025-08-14)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-5">

#### Fixes

* Improved Server-Side Editors API response serialization  
The SSE API can return only serializable values (e.g., plain objects, arrays, strings, numbers, booleans, and null).  
To accommodate the need for returning more complex values, the server will now try to serialize the value returned  
from the script into a JSON object. You can read more about syntax and response restrictions in our official  
documentation https://ckeditor.com/docs/cs/latest/developer-resources/server-side-editor-api/editor-scripts.html#syntax
* Fixed compatibility with editor bundles that contain the Line Height plugin  
Using the Line Height plugin in the uploaded bundle caused errors while using  
features that required the editor bundle. Now, the plugin can be included in an uploaded  
editor bundle.
* Fixed occasional errors when uploading editor bundles  
Previously, there was a chance of an occasional `409 Conflict` error response when  
uploading the editor bundle. Now, the editor bundles will be properly processed and uploaded.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-8">

#### Other changes

* Added `plugins_to_remove` parameter to Server-Side Editors API  
The new parameter in the request body will allow you to specify a list of plugins that should be excluded  
from the editor during script evaluation.  
This option is useful when certain plugins can interfere with proper script execution.
* Improved stability and security of Server-Side Editors API  
Improved selected aspects of Server-Side Editors API behavior and sandboxing to ensure better  
stability, reliability, and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4250-2025-07-22">

### 4.25.0 (2025-07-22)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-4">

#### Features

* Added support for the Server-side Editor API  
The Server-side Editor API (SSE API) allows for evaluating editor scripts on the server side.  
It is useful for performing complex operations on the document data, such as  
applying styles, inserting content, etc.  
To use the SSE API with an `Collaboration worker` the `APPLICATION_EXTERNAL_ENDPOINT` must be set.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D~1evaluate-script/post`  
and to our online documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-6">

#### Fixes

* Fixed an issue with frequent consecutive calls to the Document export API endpoint  
Previously, a frequent consecutive requests might have resulted in locking document exports without manual updates of revisions.  
Now, the document export is properly performed.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-9">

#### Other changes

* Added `initialData` to Collaboration snapshots  
The `initialData` improves the ability of debugging in case of Editor bundle failures.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration-snapshots`
* Extended selected Webhooks events with userId  
Webhooks events now contain the `userId` of the user who performed the action:

  * `commentthread.updated`
  * `commentthread.reopened`
  * `commentthread.removed`
  * `commentthread.restored`
  * `suggestion.removed`
  * `suggestion.restored`  
For more information, please refer to our online documentation.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4241-2025-07-01">

### 4.24.1 (2025-07-01)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-7">

#### Fixes

* Fixed Authorization for the Management Panel  
The Authorization for the Management Panel wasn’t verified properly.  
Now, the correct password is required to access the Management Panel.  
The issue was reported by Adam Wójs from [Ibexa](https://www.ibexa.co/). Thank you!

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4240-2025-06-10">

### 4.24.0 (2025-06-10)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-5">

#### Features

* Added a new Management Panel  
The Management Panel have been unified with the cloud version.  
Credentials to access the Management Panel are the same as for the old version.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-8">

#### Fixes

* Fixed comments and collaboration permissions  
Previously, there existed a possibility that during connecting  
to collaborative editing sessions with specific content and comments,  
the server incorrectly expected `comment:write` permissions.  
Because of that, the users with `comment:read` permissions were not able  
to connect to said documents.  
This version fixes that situation by correctly expecting only `comment:read` during connection in read-only mode.  
Fixed an issue with Ghost comment threads created when a user  
with `comment:read`, `document:read` and `comment:admin` permissions  
was trying to add a comment on the document. Due to incorrect permissions handling the comment thread was created without a reference in the document.

**Important notes**

  * To not introduce breaking changes and misalignment between older editor versions and Collaboration Server On-Premises the changes will take effect **only** from CKEditor5 version greater than or equal to `43.3.0`
  * All the behavior related to other permissions as well as roles is left intact
* Fixed minimap plugin handling in the editor bundles  
The minimap plugin is now disabled by default in the editor bundles.  
The plugin is disabled as it isn’t affecting the document content but could lead  
to a document conversions process to fail.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--others">

#### Others

* Improved a Webhook creation process  
A new webhook cannot be created if no access key is marked to be used for webhooks.  
It ensures that the event will contain the correct signature.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4230-2025-04-22">

### 4.23.0 (2025-04-22)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-6">

#### Features

* The Recovery snapshots feature is now enabled by default  
This means that the snapshots  
of the document will be created and saved to the configured storage in case of any failures  
during document processing.  
To disable this feature, set the `ENABLE_SNAPSHOTS=false` environmental variable.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration-snapshots`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-9">

#### Fixes

* Fixed a bug where exporting or copying documents created a new collaboration session that never expires  
Now, the new collaboration session will not be created if it does not exist.
* Fixed a bug where copying, exporting or importing documents could lead to corrupting the document  
Before, a race condition could happen when invoking the same request multiple times in a row.  
It could block a given document from further import/get/remove requests.  
Now, the race condition is fixed and the document is not blocked.
* Fixed Connection optimization feature  
Before, when the Connection optimization feature and Document storage were enabled,  
the bug led to situation where the document export was unsuccessful.  
Now, the compression is done properly and the document export is successful.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--others-2">

#### Others

* Improved logger performance and optimized memory consumption  
The logger module has been improved to reduce a memory consumption and improve performance.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4220-2025-03-11">

### 4.22.0 (2025-03-11)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-7">

#### Features

* Extended the Beta version of the Recovery snapshots feature  
In case of failed operations while using bundle-based editor, the snapshots of the document  
are now created and saved to the configured storage. This allows for recovering  
the document data in case of any failures during document processing and allows  
to track and reproduce a bug in case of a failure during the editor bundle execution.  
The recovery snapshots are kept in the storage for 30 days.  
To enable this option, set the `ENABLE_SNAPSHOTS=true` environmental variable.  
Please note that the feature is still under development and its behavior  
may be changed in upcoming releases.  
For more information, please refer to the REST API documentation at  
`/api/v5/docs#tag/Collaboration-snapshots`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-10">

#### Fixes

* Fixed the `Target closed` error  
The `Target closed` error appeared randomly while handling higher traffic. It could lead  
to a temporary performance degradation and container restarts. The error has been fixed.
* Fixed the `NOSCRIPT` Redis error  
The `NOSCRIPT` Redis error appeared when one of the Redis instances was restarted  
or the `SCRIPT FLUSH` command was executed. Now, in the case of the `NOSCRIPT` error,  
the script is loaded again to the Redis instance.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other">

#### Other

* Improved License module reliability  
The License module has been improved to handle license server unavailability.
* Updated node version to 22.14.0  
The node version has been updated to 22.14.0 improving the security, reliability  
and performance of the application.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4211-2025-02-19">

### 4.21.1 (2025-02-19)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-11">

#### Fixes

* Fixed validation for selected types of licenses  
Selected types of licenses couldn’t be validated again after 90 days from the activation  
resulting in the `Can not change the license! Wrong server time!` error.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4210-2025-01-28">

### 4.21.0 (2025-01-28)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-8">

#### Features

* Added REST API to the GET editor bundle  
The new `GET /editors/{bundle_version}` REST API endpoint allows for fetching editor bundle.  
It lets you get the exact editor bundle that is used on the server to make debugging easier.  
You can find more information in the REST API documentation available  
under `/api/v5/docs#tag/Editor-bundles/paths/~1editors~1%7Bbundle_version%7D/get`.
* Added REST API to the GET editor bundle config  
The new `GET /editors/{bundle_version}/config` REST API endpoint allows for fetching editor bundle config.  
It lets you get the editor bundle config which may be used for debugging purposes.  
You can find more information in the REST API documentation available  
under `/api/v5/docs#tag/Editor-bundles/paths/~1editors~1%7Bbundle_version%7D~1config/get`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-12">

#### Fixes

* Fixed compatibility with editor bundles that contain the Document outline plugin  
Using the Document outline plugin in the uploaded bundle caused errors while using  
features that required the editor bundle. Now, the plugin can be included into a uploaded  
editor bundle.
* Fixed support for special characters in the `document_id_patterns` parameter in the `DELETE /collaborations` endpoint  
Using special characters such as `|` in the document ID could lead to flushing  
more documents than expected, as special characters were interpreted as a part of a regular  
expression. Now, only the `*` can be used as a wildcard, as stated in the REST API documentation.  
You can find more information in the REST API documentation available under  
`/api/v5/docs#tag/Collaboration/paths/~1collaborations/delete`
* Fixed the `target` attribute support in comments  
The `target` attribute was previously lost while fetching comments.  
Now the `target` attribute is permanently preserved.
* Fixed the `/collaborations/{document_id}/save` endpoint responses  
Before, when the `/collaborations/{document_id}/save` endpoint was called for a document  
session created before enabling the Document storage, the `202` response was returned  
despite the fact that the document was not saved correctly.  
Now, in such a case, the `409` response will be returned.  
You can find more information in the REST API documentation available under  
`/api/v5/{environment_id}/collaborations/{document_id}/save`.
* Fixed OpenAPI 3 REST API Documentation compatibility  
The REST API definitions were adjusted to meet the OpenAPI 3.0.0 requirements.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-2">

#### Other

* Improved API documentations reliability  
The Environments API, Webhooks API and REST API were standardized.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4202-2024-11-19">

### 4.20.2 (2024-11-19)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-9">

#### Features

* Added a beta version of the Recovery snapshots feature  
After the collaborative session has been finished, the raw copy of document data is  
saved to a configured storage. Thanks to this, in case of any failures during document  
processing, there will be possibility to fetch raw document and share it with  
the CKEditor support to recover the document data.  
The recovery snapshots are kept in the storage for 30 days.  
To enable the option, set the `ENABLE_SNAPSHOTS=true` environmental variable.  
Please note that the feature is still under development and its behavior  
may be changed in upcoming releases.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-13">

#### Fixes

* Fixed error handling when a revision for a documentID already existed in case of \[POST\] `/documents`  
Such a situation could lead to data inconsistency. Now the 400 error will be returned.
* Fixed error handling for a case where revisions with duplicated from/to pair was added  
Such a situation could lead to data inconsistency. Now the 400 error will be returned.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-3">

#### Other

* Extended the `collaboration.document.updated` webhook event with an `updated_by` field  
The `updated_by` property contains ID of the user who updated the document recently.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4201-2024-10-08">

### 4.20.1 (2024-10-08)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-4">

#### Other

* Improved reliability of the license module
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4200-2024-08-27">

### 4.20.0 (2024-08-27)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-10">

#### Features

* Added REST API to the GET business logs  
The new `GET /insights/business-logs` REST API endpoint allows to fetch business logs.  
It allows for fetching logs and share them in a form of JSON, making sharing logs easier.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Insights/paths/~1insights~1business-logs/get`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-5">

#### Other

* Improved validation of the Pagination cursor  
Now the pagination cursor is validated properly.
* Improved reliability of the license module
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4192-2024-07-24">

### 4.19.2 (2024-07-24)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-6">

#### Other

* Improved reliability of the license module
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4191-2024-07-18">

### 4.19.1 (2024-07-18)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-14">

#### Fixes

* Fixed a bug where the `unlinkedAt` property was lost after a comment was resolved or reopened.  
Before the fix, the `unlinkedAt` property was lost after a comment was resolved or reopened.  
This resulted in the comment thread disappearing from the comment archive after a reconnection or page refresh.  
Now the property is set to its previous value.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4190-2024-07-16">

### 4.19.0 (2024-07-16)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-11">

#### Features

* Extend the `GET /collaborations/{document_id}/exists` endpoint with the Document storage status  
The `GET /collaborations/{document_id}/exists` accepts now additional `include_storage`  
query parameter. After the parameter is set, the response includes the `exists_in_storage`  
property, that indicates if the given document is stored in the Document storage or not.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D~1exists/get`.
* Extend the `GET /storage/{document_id}` endpoint with a status of stored document  
The `GET /storage/{document_id}` returns now the information if the document in Document storage is stored properly.  
When the `?details=true` query parameter is set, then the response will include the `is_stored_properly` property.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Storage/paths/~1storage~1%7Bdocument_id%7D/get`.
* Extend the `GET /storage` endpoint with a status of stored documents  
The `GET /storage` returns now the information if each document from the Document storage is stored properly.  
The response will include the `is_stored_properly` property for every document on the lists.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Storage/paths/~1storage/get`.
* Filter the `GET /storage` response by the status of documents  
The `GET /storage` accepts now an additional parameter `is_stored_properly` that indicates if all,  
correctly stored or only corrupted documents should be returned.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Storage/paths/~1storage/get`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-15">

#### Fixes

* Fixed a bug where corrupted document could be copied by using the Copy API  
Now, copying corrupted documents is blocked to prevent a case where corrupted document is duplicated without any notice.  
It will help to detect cases of currupted document earlier.
* Fixed a bug where `last_updated_at` and `last_updated_by` were not updated after document was imported.  
Now, after a document is removed and imported again, the `last_updated_at` will be set to a date of document import.  
The `last_updated_by` will be set to `null`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-10">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4180-2024-06-04">

### 4.18.0 (2024-06-04)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-12">

#### Features

* Triggerring the document storage  
A new `PUT /api/v5/collaborations/{document_id}/save` method allows for manually  
triggerring a process of saving a document to the document storage without removing  
a collaboration session.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D~1save/put`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-16">

#### Fixes

* Fixed validation for comment’s type  
While using the `POST /api/v5/{environment_id}/documents` endpoint,  
only comments having `type` with value `1` or `2` will be accepted.  
The validation was introduced as no other types exists.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Documents/paths/~1documents/post`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-11">

#### Other changes

* Improved Document Storage to avoid breaking documents while connecting  
A process of creating a collaborative session from a document stored in a Document Storage will be blocked  
if an editor bundle will be not uploaded. To create a collaborative session from a document from a Document Storage  
the document needs to be processed by the editor bundle.  
Now, an attempt of creating collaborative session without editor bundle will be blocked to prevent document corruption.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4173-2024-04-23">

### 4.17.3 (2024-04-23)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-17">

#### Fixes

* Fixed displaying the Webhooks tab in the Management Panel  
The Webhooks tab is now displayed correctly in the Management Panel.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-12">

#### Other changes

* Improve the Copy method from the Documents REST API  
The `POST /api/v5/{environment_id}/documents/{source_document_id}` method accepts  
the `bundle_version` parameter now. Thanks to the parameter, the `bundle_version`  
that will be used to run a new session of a copied document can be set explicitly.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4172-2024-03-12">

### 4.17.2 (2024-03-12)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-18">

#### Fixes

* Fixed support for the `|` character in the document ID  
Before, using the pipe `|` character in the document ID could cause problems with applying correct  
document privileges. Now the pipe character is supported and can be used in a document ID.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-13">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4171-2024-01-23">

### 4.17.1 (2024-01-23)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-14">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4170-2023-12-19">

### 4.17.0 (2023-12-19)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-13">

#### Features

* Added REST API endpoints for the API Secret and Access Key management  
The new REST API allows you to get, create, and remove API Secrets and Access Keys.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Environments`.
* Added possibility to disconnect a user from a particular collaboration session or a set of collaboration sessions  
Introduced a new query parameter, `document_ids` to the `/api/v5/{environment_id}/users/{user_id}/collaborations` endpoint which takes a list of collaboration session IDs separated by a comma.  
The new parameter makes it possible to provide a list of documents from which the user should be disconnected.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-19">

#### Fixes

* Increased the number of available connections to a PostgreSQL database, in a connection pool  
Before, the number of connections could be insufficient while the application was handling higher traffic, depending on a use-case.  
Now the number of available connections has been increased, to cover the case.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-15">

#### Other changes

* Extended the collaboration details response with properties related to the last update  
The new fields are `lastUpdatedAt` and `lastUpdatedBy` and will contain the date of the last update and the ID of the user performing it respectively. It will be returned for the below REST API endpoints:

  * `GET /api/v5/collaborations/{collaboration_id}/details`
  * `GET /api/v5/collaborations/{collaboration_id}?details=true`
* Extended the document storage details response with the date of the last save in the storage  
When exporting the content of the document from the storage with details using the `GET api/storage/{document_id}?details=true` endpoint, the date of the last save will also be included in the response.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4162-2023-11-07">

### 4.16.2 (2023-11-07)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-16">

#### Other changes

* Improved performance of the license module
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4161-2023-10-06">

### 4.16.1 (2023-10-06)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-17">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.  
The above update patches the security vulnerability related to the heap buffer overflow risk.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4160-2023-09-27">

### 4.16.0 (2023-09-27)

The newest version of CKEditor Cloud Services On-Premises introduces a three-month webhook request retention.  
Thanks to this, the increasing number of webhook requests will not take up too much space as time goes by.  
To allow the removal of outdated requests without introducing any interruptions or blocking the application the old  
requests have been archived. Note that the data will **not** be deleted permanently. If you want to restore your  
old webhook requests, please contact our support - https://ckeditor.com/contact/.

All webhooks behaviors stay unchanged.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-14">

#### Features

* Added REST API for Revision History  
The new REST API allows you to get, create, and remove revisions of the document.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Revisions`.
* Added REST API endpoint to disconnect a single user from all active editing sessions  
The `DELETE:/users/{user_id}/collaborations` endpoint can be used to force a user to disconnect from all documents in case of e.g. privileges update.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Collaboration/paths/~1users~1%7Buser_id%7D~1collaborations/delete`.
* Added a possibility to flush specific documents by providing a list of their IDs or IDs containing wildcards  
The `DELETE:/collaborations` method has been extended with the `documentIdPatterns` query parameter. A list of document IDs or ID patterns is accepted.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Collaboration/paths/~1collaborations/delete`.
* Added support for MySQL 8  
From this version, the CKEditor Collaboration Server On-premises will be tested with MySQL in version 8.
* Added support for PostgreSQL 14  
From this version, the CKEditor Collaboration Server On-premises will be tested with PostgreSQL in version 14.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-20">

#### Fixes

* Fixed a problem while connecting with a database thru the TLS connection  
The TLS connection wasn’t possible, now TLS can be used properly.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-18">

#### Other changes

* Improved licensing mechanism  
A race condition while quick connecting and disconnection was solved.
* Improved mechanism to release unused database connections
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4151-2023-08-22">

### 4.15.1 (2023-08-22)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-21">

#### Fixes

* Fixed support for the CKEditor Nightly releases  
CKEditor Collaboration Server now fully supports the CKEditor Nightly releases.
* Fixed validation for authentication tokens  
JWT tokens with `-` are now accepted.
* Fixed usage of the `force` flag with the `DELETE:/collaborations/{document_id}` REST API endpoint  
Now, when the `force` flag is set to `true`, connected users are properly disconnected from the editing session while flushing the document.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Collaboration/paths/~1collaborations~1%7Bdocument_id%7D/delete`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-19">

#### Other changes

* Improved error handling for SQL databases  
Some errors from the SQL database are now handled and solved by default without throwing them.  
Other errors are now more readable.
* Extended the `GET:/users` REST API endpoint response  
The response now contains `first_connected_at` and `last_connected_at` properties.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Users/paths/~1users/get`.
* Simplified the `POST:/documents` REST API endpoint request  
Now, the `requestId` for revisions and `documentId` for comments and suggestions are not required anymore while using the `POST:/documents` endpoint.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Documents/paths/~1documents/post`.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4150-2023-07-11">

### 4.15.0 (2023-07-11)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-15">

#### Features

* Added support for synchronous document import  
A document can now be imported directly into the document storage without initializing a new editing session.  
It can be done in the REST API through the POST method from the `/storage` endpoint.  
You can find more information in the REST API documentation available under `/api/v5/docs#tag/Storage/paths/~1storage/post`.
* Added support for revision history in the `/documents` REST API  
Document revisions can be imported and exported through the `/documents` REST API.  
You can find more information in our online documentation or the REST API documentation available under `/api/v5/docs#tag/Documents/`.
* Extended support for multi-root editors  
Added the possibility to preserve, export, and initiate the attributes for multi-root documents through webhooks and REST API.  
You can find more information in our online webhooks documentation or the REST API documentation available under `/api/v5/docs#tag/Collaboration` and `/api/v5/docs#tag/Documents`.
* Added support for the `MIGRATE_ONLY` mode  
The application can be run now in a mode, where only database migrations will run, after migration the instance will be stopped. It gives more flexibility to the CKEditor Collaboration Server On-premises upgrade process.  
You can find more information in our online documentation.
* Added support for multiple API secrets  
A single environment can include multiple API secrets, it allows for rotation of the API secrets without any downtime.  
The new API secrets can be managed from the “API secrets” tab in the Management Panel.  
You can find more information in our online documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-22">

#### Fixes

* Fixed support for special characters in IDs  
Special characters are now fully supported in the document, comment, suggestion, user, and other IDs.
* Fixed performance issues with database connections under heavy load  
User connection peaks do not cause application performance degradation.
* Fixed problem with failing heartbeat  
The heartbeat mechanism was reworked to be more reliable.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-20">

#### Other changes

* Improved notifications and errors in the license mechanism  
The notifications and errors are now more verbose.
* Improved mechanism to manage database connections  
Idle and stale connections from a pool are now closed earlier.  
The number of connections in a single pool has been increased to handle more traffic.
* Optimized the memory usage by the real-time collaboration feature
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4140-2023-05-30">

### 4.14.0 (2023-05-30)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-16">

#### Features

* Added support for the `REDIS_USER` variable  
The new environmental variable allows for setting the user while connecting to a Redis instance.  
More details can be found in the online documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-23">

#### Fixes

* Fixed memory leak while using the Easy Image feature  
Memory was not released after getting an image under some circumstances.
* Fixed a problem with application performance while connecting thousands of users in a period of time  
When user connected thousands of unique users in a period of time application was restarting or freezing.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-21">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4130-2023-04-18">

### 4.13.0 (2023-04-18)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-17">

#### Features

* Added support for the comments archive feature  
The new CKEditor 5 comments archive feature is now supported.
* Added the `collaboration.document.update.exported` webhook event  
The new webhook is triggered whenever a collaboration session is updated, has ended, or when the last user disconnects.  
The webhook’s payload contains the document content.  
You can find more information about it in our online documentation.
* Added support for the `comment:modify_all` privilege  
The new privilege allows to remove or modify a single comment of another user.
* Added support for case sensitive ids in new installations  
The case of letters used in identifiers is now distinguished. Eg., `userId-1` is now different from `UserId-1`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-24">

#### Fixes

* Improved logs printed when a database migration fails  
The logs provide more information about the failed migration. It will make it easier to debug such cases.
* Improved the migrations script  
The script to run migrations is now insensitive to restarts and shutdowns of the application during database upgrades.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-22">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4121-2023-02-28">

### 4.12.1 (2023-02-28)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-25">

#### Fixes

* Fixed minor UI bugs in the Management Panel

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-23">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4120-2023-01-24">

### 4.12.0 (2023-01-24)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-18">

#### Features

* Added possibility to omit comments and suggestions while using `/documents` API  
It allows skiping exporting comments or/and suggestions while exporting and importing documents using the `/documents` API.  
This would allow importing the document without comment and/or suggestions and their respective markers.
* Added filters to the Webhooks Requests view in the Management Panel  
Filters allow checking requests related to selected events with a chosen status code.
* Improved UX of the Insight Panel view in the management panel  
It is now possible to set a relative time frame for logs, so e.g. logs from the last hour can be checked.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-26">

#### Fixes

* Fixed random timeouts while processing documents stored in the Document Storage
* Fixed date parsing in the `/documents` API  
The date in comments added along with a document can now be provided as a Date ISO8601 String and as a timestamp.
* Fixed problem with CORS restrictions  
Now all necessary to communicate headers are allowed by the `Access-Control-Allow-Headers` header.
* Fixed returning the correct version of a document after the session flushing  
Previously the incorrect document version was returned after the document session was flushed.  
The bug affected the following REST API’s endpoints:

  * GET `collaboration/:documentId?details=true`
  * GET `documents/:documentId`  
and webhooks:

  * `collaboration.document.exported`
  * `collaboration.document.export.failed`
  * `collaboration.document.recovered`

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-24">

#### Other changes

* Updated Node to Node 18
* Improved performance and stability of Documents workers  
It will affect all features that use the Editor Bundle.  
The mechanism which runs the Editor Bundle inside of the Server has been refactored and optimized.
* Improved socket refresh mechanism  
Every instance of the CKEditor Collaboration On-premises service now only refreshes its own connections instead of all.
* Added version of the CKEditor Collaboration On-premises to logs
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4110-2022-11-29">

### 4.11.0 (2022-11-29)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-19">

#### Features

* Added the Users REST API  
The new REST API allows adding new user data to and getting the data from the CKEditor Collaboration Server.  
You can find more information in our online documentation or in the REST API documentation available under `/api/v5/docs#tag/Users`.
* Added the documents `version` field to selected webhooks  
The new field contains the version of the document which is included in a webhook payload.  
It can be used to ensure that a stored document will not be overwritten with an older version.  
The `version` field has been added to:

  * `collaboration.document.exported`
  * `collaboration.document.export.failed`
  * `collaboration.document.recovered`
* Added documents `version` field to REST API responses  
The new field contains the version of a document that was requested.  
It can be used to ensure that a stored document will not be overridden with an older version.  
The `version` field has been added to:

  * GET `collaboration/:documentId?details=true`
  * GET `documents/:documentId`

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-27">

#### Fixes

* Fixed random `Connection hasn't been authenticated in a period of time` errors  
The error occurred when a computer with a document opened in a browser was put into sleep mode for a few hours.  
After waking up the device the collaboration was still possible, however, numerous errors in the browser console were prompted.  
The fix requires CKEditor 5 in version v35.3.0 or newer.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-25">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4101-2022-11-07">

### 4.10.1 (2022-11-07)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-26">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--4100-2022-10-18">

### 4.10.0 (2022-10-18)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-20">

#### Features

* Added ability of import, export and remove documents with all related data  
With the new feature a document can be imported, exported or removed with all assigned data, such as comments and suggestions.  
You can find more information in our on-line documentation or in the REST API documentation available under `/api/v5/docs#tag/Documents`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-27">

#### Other changes

* Improved performance of document export  
Exporting documents takes less time for environments with `Connection optimization` enabled.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--490-2022-09-06">

### 4.9.0 (2022-09-06)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-21">

#### Features

* Added the Copy feature  
The new feature allows to copy documents with their data by using the REST API method `/api/v5/{environment_id}/documents/{source_document_id}`.  
More information can be found in the online documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--fixes-28">

#### Fixes

* Fixed urls in the management panel  
Links containing details of connecting CKEditor Collaboration Server with the CKEditor 5 point to the latest version of documentation now.
* Fixed urls in returned errors  
Links placed in the error messages, action and explaination field points to the latest REST API endpoints version.
* Fixed support for regular expressions in the editor config  
The regular expression will be now interpreted correctly while using the GHS plugin in the editor bundle.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-28">

#### Other changes

* Increased size limit for attributes in suggestions and comments  
While using MySQL there was a limit of 64 kB of attributes. It has been changed to 16 MB.  
The change allows to store more attributes. The value for PostgreSQL stays without changes, 1 MB.
* Increased default ping interval and timeout for socket communication  
The increased value stabilizes the pings mechanism in case of a slow internet connection or when documents in the editor are processed slowly.
* Improved application performance
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--480-2022-07-26">

### 4.8.0 (2022-07-26)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-22">

#### Features

* Added support for multi-root editor bundles  
Multi-root editor bundles can be now used with the CKEditor Collaboration Server On-Premises.
* Added support for revision resuming  
The revision resuming feature now works for Real Time Collaboration features that use an editor bundle uploaded to the Cloud Services server.
* Added `collaboration.document.exported` webhook event  
The new webhook is triggered whenever a collaboration session has ended and the document data has been successfully exported while the document storage is disabled.
* Added `collaboration.document.export.failed` webhook event  
The new webhook is triggered whenever the system cannot convert document operation after a collaboration session has ended. It works only when the editor bundle is uploaded and the document storage is disabled.
* Added `GET:/collaboration/{document_id}/sockets` REST API method  
The new endpoint returns a list of sockets IDs connected to a document with the provided ID.
* Extended `GET:/collaboration/{document_id}/users` REST API method  
Now the endpoint returns a list of user IDs along with sockets IDs when the `?details=true` query parameter is passed.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-29">

#### Other changes

* Improved performance  
Parts of the application were reviewed and optimized.  
As a result, the time needed to fully process requests has been reduced.
* Added server version to Management Panel and Info Page  
The version of the currently running CKEditor Collaboration Server On-Premises is now displayed in the Management Panel and on the Info Page.  
The version can be now checked by visiting `/panel` and `/` in the browser.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--470-2022-06-14">

### 4.7.0 (2022-06-14)

Legacy REST API versions (v1, v2) have been removed

Due to the changes in the license key validation for Revision History, in order to use the latest version of Collaboration Server On-Premises, please make sure that you provide the correct (latest) license key that you can find in the CKEditor Ecosystem Dashboard.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-23">

#### Features

* Enabled support for Revision History with editor bundle  
Using the Revision History feature with an editor bundle allows to limit data transferred between CKEditor and the Collaboration Server.
* Introduced REST API v5  
The new version of the REST API contains more consistent requests and response payloads.  
Version 4 has been deprecated.  
The documentation for the new version 5 was reviewed and improved by adding missing information and rephrasing  
parts of the already existing content.  
Version 5 contains one _breaking change_: the `/documents` resource was renamed to `/storage`.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes">

#### Bug fixes

* Fixed removing comments and suggestions in imported documents  
Previously, importing a document collaboration session with suggestion and comment markers resulted in an incorrect database state. As a result, an attempt to delete such comments or suggestions would not mark them as deleted. Moreover, corresponding webhooks would not be sent. Now, the delete mechanism works correctly.
* Fixed removing documents with active sessions from document storage  
Now, as long as there is an active editing session, an attempt to remove a document from the document storage will result in a 409 error.  
This prevents breaking a currently edited document. To remove a stored document that has an active editing session,  
flush it manually or wait for the session to expire.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-30">

#### Other changes

* Increased maximum size of Web Socket message to 100 MB  
Increasing the limit allows to initialize collaboration sessions with bigger documents.
* Increased maximum length of webhooks URL to 512 characters
* Increased history compression threshold to 15k operations  
It improves the performance of CKEditor 5 and Revision History by limiting auto-save usage.
* Improved webhooks retries mechanism  
The webhooks mechanism has been optimized. The reliability of retries has been also improved.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.
* Added support for Revision History licensing

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--460-2022-05-05">

### 4.6.0 (2022-05-05)

Legacy REST API versions (v1, v2) of selected endpoints have been removed

The change affects:

* all `/comments` endpoints
* `/documents/{document_id}/users`

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-24">

#### Features

* Added Insights Panel  
The new tool allows to access the logs of CKEditor Collaboration Server On-Premises.  
The Insights Panel can be found in the Management Panel after selecting an environment.
* Added support for ARM64v8 CPU architecture  
CKEditor Collaboration Server On-Premises can now be run on machines with the ARM64v8 CPU architecture.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-2">

#### Bug fixes

* Fixed adding suggestion to tables  
Previously, adding a suggestion for inserting a row and a suggestion for inserting a column that was crossing  
the suggested row resulted in inappropriate behavior. Deleting the row suggestion would also delete  
the column suggestion. Now, suggestions can be applied to tables correctly.
* Fixed `Content-Type` HTTP header in `GET:/collaborations/{document_id}`  
The returned header was changed from `application/json` to `text/html` as the endpoint returns data  
in the HTML format.
* Fixed user count returned from `/organization-statistics`  
The `/organization-statistics` endpoint used to count the same user from different environments as one user,  
while the licensing mechanism treats such users as distinct ones. Now, the number returned from the endpoint  
matches the current license usage.
* Fixed server error while adding comments without `user` via REST API  
The `user` field is now handled correctly and a meaningful error (status 400) will be returned if the provided  
value is invalid.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-31">

#### Other changes

* Improved licensing mechanism  
The licensing mechanism is now more stable and reliable. The details about the license are now displayed in  
the Management Panel. The problem with counting concurrent users has been fixed. Now, the limits are checked  
immediately upon connection to the server.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--450-2022-03-22">

### 4.5.0 (2022-03-22)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-25">

#### Features

* Added support for the Real-time Revision History feature
* Added mechanism for soft delete in comments and suggestion  
The removal mechanism for comments and suggestion has been changed. Now the comments and suggestions are marked as removed  
instead of removing them permanently. More information can be found in our online documentation.  
Comments and suggestions can be removed permanently via the REST API.
* Added a default page for the root address  
Now the root address of CKEditor Collaboration Server On-Premises shows a page with useful links.  
Before the change, nothing was displayed.
* Added the `/collaborations/{document_id}/details` endpoint to the REST API  
The new endpoint returns details about the active collaboration session assigned to a given document.  
It returns the ID of the session, the bundle version which was used to create the session, and the version of the document.  
In addition, the response contains data about the previous session: its ID and the ID of the last operation.  
More information can be found in the REST API documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-3">

#### Bug fixes

* Fixed a support for editor bundles containing CKEditor 5 v33.0.0  
It is now possible to upload editor bundles with collaboration plugins in version 33.0.0 without any errors.
* Fixed the `Cannot find suggestion` and `track-changes-user-not-found` errors while using Track Changes feature with tables  
The errors occurred in the CKEditor while removing suggestions related to tables.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-32">

#### Other changes

* Improved socket ping mechanism  
The ping mechanism has been improved, it provides better stability of a connection and improves compatibility with different browsers.
* Updated dependencies  
Updated selected dependencies to the latest versions, improving performance and security.
* Improved error messages  
Some of the errors contain more detailed messages. Updated errors include explanations and possible actions to solve the problem.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--440-2022-02-08">

### 4.4.0 (2022-02-08)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-26">

#### Features

* Added support for IPv6  
Connection over IPv6 is now supported for Redis databases.  
Given an IP address, the server will detect if IPv6 or IPv4 has been used.  
However, when a domain is provided, IPv6 must be forced by  
setting the `REDIS_IP_FAMILY=6` environment variable when running the server.  
More information can be found in our on-line documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-4">

#### Bug fixes

* Reduced the number of emitted `storage.document.saved.failed` events  
The event was emitted multiple times when an editor bundle was missing.
* Fixed removing comments and suggestions from the database when the PostgresSQL is used  
Comments and suggestions were not removed after accepting or rejecting suggestions.  
As a result, accepted suggestions and related comments were returned by the REST API.  
Now, after accepting or rejecting a suggestion, the data is removed from the database.  
The webhook events related to removing and restoring comments or suggestions are also correctly emitted.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-33">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--430-2022-01-18">

### 4.3.0 (2022-01-18)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-27">

#### Features

* Added a new webhook event `collaboration.document.updated`  
The new event is emitted:

  * every 5000 versions of the document, or
  * every 10 minutes while the document is being edited, or
  * when the last user disconnects from the collaboration session.
* Added the `wait` parameter to `[DELETE] v4/collaborations/:document_id`  
The parameter allows to flush a document synchronously.  
By default the document is flushed asynchronously.  
The synchronous request can be useful for cases when documents needs to be saved or when preparing a collaboration session.
* Renamed webhooks  
Currently the names of events indicate whether the event is a real-time collaboration event or a document storage event.  
Backward compatibility has been kept.

  * `document.user.connected` \-> `collaboration.user.connected`
  * `document.user.disconnected` \-> `collaboration.user.disconnected`
  * `document.removed` \-> `collaboration.document.removed`

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-5">

#### Bug fixes

* Fixed the webhook retry mechanism  
The webhook retry mechanism was not working, so failed webhook requests were not sent again.  
Now it has been fixed and works as expected.  
Webhook requests that return statuses other than 2xx are resent as configured in the management panel.
* Improved the reconnection mechanism  
The changes introduce an improved reconnection mechanism, included in CKEditor 5 version `31.1.0`, which now handles more reconnection cases.
* Added a `Content-Length` header to webhooks requests  
The header fixes the errors during receiving webhooks request on the Microsoft Azure Cloud Platform.
* Fixed an issue with using both the document storage and the import-export features at the same time
* Fixed the problem with using a database as a storage

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-34">

#### Other changes

* Changed the default collaboration session duration to 24 hours  
It helps to prevent problems during longer disconnections.  
The time can be changed manually by setting the amount of milliseconds in the environment variables:

  * `COLLABORATION_EXPIRATION_TIME_STORAGE` \- for environments with the document storage feature enabled
  * `COLLABORATION_EXPIRATION_TIME` \- for environments without the document storage feature
* Updated Node.js to version 16
* Updated dependencies  
Updated selected dependencies to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--420-2021-11-16">

### 4.2.0 (2021-11-16)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-28">

#### Features

* Added a new method for the Webhooks in Cloud Services Management REST API  
Added a new method `/webhooks/{webhooks_id}/requests/metadata`.  
The new method fetches webhook’s requests list without requests body.
* Optimized a way of fetching a webhook’s requests in the CKEditor Management Panel  
The webhook’s requests are now fetched using a new, more lightweight method.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-6">

#### Bug fixes

* Fixed race condition in suggestions and comments  
While quick removing and restoring suggestions and comments, a race condition occasionally occurred.
* Fixed memory leak in the Easy Image  
Downloading images from Easy Image could lead to memory leaks.
* Fixed decryption in webhooks requests  
Huge webhook’s request’s payloads stored in a database couldn’t be decrypted.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-35">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.  
From this version on, the Docker Engine 20.10 or higher is recommended.
* Updated base docker image (Alpine Linux) from version 3.12 to 3.14

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--410-2021-10-05">

### 4.1.0 (2021-10-05)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-29">

#### Features

* Add POST method to Suggestions REST API

The method allows to add a suggestion data using REST API.

* Add PUT method to Suggestions REST API

The method allows to update a suggestion data using REST API.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-7">

#### Bug fixes

* Fixed removing collaboration session after expiration time for imported documents without connected users  
The documents which were imported using REST API will now start a collaboration session.  
Thanks to this, imported documents will be processed even if no user connects to them.
* Fixed a problem with washout colours in PNG files processed using the Easy Image  
The quality for PNG files has been increased; thanks to that the colours in PNG images will stay the same as in the original file.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-36">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--400-2021-08-24">

### 4.0.0 (2021-08-24)

The internal process of testing new releases has been improved.  
Starting from version 4.0.0, the new testing process will be applied. This allows us to improve the quality and reliability of the following releases.  
This change does not affect the CKEditor OnPremises Collaboration Server behaviour.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-30">

#### Features

* Increased the maximum length of comments’ content  
The limit of comments contents’ length has been increased to 65000 chars.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-8">

#### Bug fixes

* Fixed a bug related to restoring formatting suggestions  
User will be able to restore formatting suggestions.
* Fixed a bug that causes occasional deadlocks while inserting into the SQL database  
In case of deadlock the insert operation will be retried.
* Fixed a bug related to pending operations  
During document load, the document is saved. It fixes documents after a previous interrupted save.
* Fixed the GET `/organization-statistics` method  
This method returns correct number of users connected to the Collaboration Server.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-37">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.
* Added more readable information about API secret to the management panel  
Updated information describing the API secret

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--3130-2021-07-05">

### 3.13.0 (2021-07-05)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-31">

#### Features

* Added metrics logs  
The new logs allow to monitor the performance and stability of the Collaboration Server On-Premises.  
More information can be found in the online documentation.
* Added a mechanism to prevent accidental disabling of the document storage feature in the Management Panel  
Before disabling the document storage feature in the Management Panel, the user will be asked for confirmation.
* Added the current license information to the Management Panel  
The possibility of checking the current users’ limit and expiration time has been added to the Management Panel.
* Added support for Redis TLS  
Support for TLS connection with Redis databases has been added. More information can be found in our online documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-9">

#### Bug fixes

* Added the `attributes` field to the comment’s webhooks  
The field was missing in the payloads of webhooks related to the `comment.added` and `comment.updated` events.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-38">

#### Other changes

* Updated dependencies  
Updated a part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--3120-2021-05-31">

### 3.12.0 (2021-05-31)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-32">

#### Features

* Added support for a TLS connection to PostgreSQL  
Added new configuration to enable connecting to a PostgreSQL database using a TLS connection without passing additional CA. Added an option to establish the connection to the server with an unverified certificate as well.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-10">

#### Bug fixes

* Added protection against loading incomplete document  
Document loading now waits for the completion of processing the most recent save operation. It fixes a problem with loading documents containing incomplete data.
* Removed false-positive log entries about connection timeout  
A closed browser tab or an exceeded user limit no longer result in a `Disconnect a socket. A connection hasn't been authenticated in a period of time` log entry.
* Fixed setting the `created_at` property in comments REST API  
Setting the `created_at` property while creating comments through REST API is no longer ignored.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-39">

#### Other changes

* Introduced new E2E tests  
New E2E tests have better stability and performance than the previous ones.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--3110-2021-04-28">

### 3.11.0 (2021-04-28)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-33">

#### Features

* Added a new implementation of Easy Image  
The new implementation of Easy Image focuses on performance improvements.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-11">

#### Bug fixes

* Added a few fixes related to the document storage feature  
Improved stability and reliability of the feature and fixed issue with saving comment markers after compressing already compressed document.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-40">

#### Other changes

* Increased document data expiration time for documents with enabled document storage feature  
Thanks to this, collaboration sessions for documents that use the Document Storage feature are not removed after 1h and are loaded faster. Additionally, it resolves problems with connecting to non-existing documents - documents removed because of some time of the inactivity - for example, night break.
* Updated dependencies  
Updated a part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--3100-2021-03-31">

### 3.10.0 (2021-03-31)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-34">

#### Features

* Added REST API endpoint `/v4/environment-statistics` which can be used to check environments statistics  
Currently this endpoint returns number of connected users to the particular environment with division into anonymous and non-anonymous.
* Added sorting option for Webhooks and Webhooks requests view in the Management Panel  
A list of Webhooks and Webhooks requests can be sorted by creation/sent data.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-12">

#### Bug fixes

* Stabilized the collaboration features  
Stabilized the connection optimization and document storage features. Resolved the issue with missing content during document compression.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-41">

#### Other changes

* Reduced the number of logs  
Stopped logging 4xx status code responses and error stack-traces.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--391-2021-02-22">

### 3.9.1 (2021-02-22)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-13">

#### Bug fixes

* Displayed the proper REST API version in the Management Panel  
The REST API link in the API Configuration section points to the latest version.
* Stabilized the collaboration features  
Stabilized the connection optimization and document storage features. Resolved the issue with missing content during document compression.
* Reduced the number of logs  
Remove non-meaningful logs such as:

  * “Type comments-v2 doesn’t match to the service”
  * “Skip sending changes to documents service”

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--390-2021-01-28">

### 3.9.0 (2021-01-28)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-35">

#### Features

* Added REST endpoint for checking if editor bundle exists  
Added a new REST API endpoint `/v4/editors/{ bundleVersion }/exists` which can be used to check if the editor bundle with the specific `bundleVersion` has been uploaded.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-14">

#### Bug fixes

* Stabilization of collaboration features  
Stabilized document storage and connection optimization features for editors with EasyImage and PasteFromOffice plugins.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--380-2020-12-15">

### 3.8.0 (2020-12-15)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-36">

#### Features

* Introduced webhooks retries  
The retries system allows receiving webhooks that were unsuccessfully sent.  
Such a case can occur when the customer application is not able to receive webhooks sent by On-Premises server properly.  
Webhooks retries configuration has been added to the Management Panel.
* Added document restore feature  
Added new REST API endpoint `/v4/collaborations/{document_id}/restore` which can be used when access to the document has been blocked due to the inability to save new operations in the document.  
Such situation can only occur when the documents storage is turned on and unexpected error occur caused by custom plugins added with the uploaded editor.
* Added immediate document save in the storage after disconnecting all users  
Previously, to get the final version of the document saved in storage, the collaboration session had to expire (1 hour) or be manually removed (by REST API).  
Now, when all users disconnect from the document, it is immediately saved in the storage.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-15">

#### Bug fixes

* Fixed errors related to collaboration features  
Errors:

  * `track-changes-adapter-missing-getsuggestion: Adapter not set or is missing 'getSuggestion()' method.`,
  * `invalid-license-key: Invalid license key.`  
that occurred during saving a document in the storage or compressing operations have been fixed.
* Allowed to upload and use editor bundle with EasyImage plugin by collaboration features  
Previously, it was not possible to upload and use the editor that contained `EasyImage` plugin.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-42">

#### Other changes

* Improved the mechanism of saving document changes in the document storage  
The improvements made allow to save all operations in the document until the operation causing the save error occurs.  
These changes reduce data loss to a minimum in case of document saving error.
* Improved race-condition mechanism for operations applied to the documents in the collaborative session
* Improved the performance for checking the existence of the editor bundle
* Remove characters limit for attributes in Track Changes feature  
The size limit of objects that can be stored in suggestion attributes (1024 characters) has been removed.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--371-2020-11-02">

### 3.7.1 (2020-11-02)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-16">

#### Bug fixes

* Fixed errors related to collaboration features  
Errors:

  * `split-operation-graveyard-position-invalid: Graveyard position invalid.`,
  * `move-operation-nodes-do-not-exist: The nodes which should be moved do not exist`,
  * `Cannot read property 'is' of undefined`  
that occurred during saving a document in the storage or compressing operations have been fixed.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-43">

#### Other changes

* Added detailed error about requests restrictions for editor bundle
* Improved stability of collaboration worker by preventing unnecessary retries during failed processing and by skipping requests with empty data.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--370-2020-10-06">

### 3.7.0 (2020-10-06)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-37">

#### Features

* Added support for CKEditor 5 in version 23.0.0
* Added collaboration documents REST endpoint  
Added new REST endpoint ( GET `/collaborations` ) for getting list of documents ids for the specified environment that are being edited.
* Added flush all documents data REST endpoint  
Added a new REST API method ( DELETE `/collaborations` ) for flushing all documents for the environment (by default, the flush will succeed if there are no connected users to document).
* Added possibility to test editor bundle using document content sent by customer
* Added mechanism to block the collaboration writing when a document can’t be saved in the storage  
Collaboration can be blocked when the document storage is turned on and document save in the storage fails. It prevents from adding new operations by users because there is no sense to store new operations which can’t be applied to the document. When the document is marked as stored not properly, connection to them is blocked too.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-17">

#### Bug fixes

* Improved performance for bigger documents  
Working with large documents could have a negative impact on working with other smaller documents. Now, this problem should not generate an impact on other documents.
* Fixed REST API versioning  
Improved error handling when the endpoint does not exist and improved documentation for endpoints with multiple versions.
* Improved editor bundle validation  
Returned an original error from the browser during editor bundle validation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-44">

#### Other changes

* Reduce the number of tests  
The execution of all tests took about 13 minutes but they checked various extreme edge cases, which are tested many times by us. For this reason, we have reduced the number of tests.  
The main components/features of the application are tested by the current set of tests to confirm that the application is working properly.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--362-2020-09-02">

### 3.6.2 (2020-09-02)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-18">

#### Bug fixes

* Added support for using other editors than `ClassicEditor` by collaboration features like: document storage, import/export, and connection optimization.  
Previously, collaboration features could only be used when the uploaded editor bundle based on `ClassicEditor`.  
Currently, it is possible to use editors like: `InlineEditor`, `BalloonEditor`, `BalloonBlockEditor`, and `DecoupledDocumentEditor` as the basis for the uploaded editor bundle.
* Added support for collaboration plugins.  
Currently, it is possible to upload editor bundle which contains plugins such as: `RealTimeCollaborativeEditing`, `RealTimeCollaborativeComments`, `RealTimeCollaborativeTrackChanges`, `PresenceList` or `Autosave`.
* Allowed to pass SSL certificates to database driver used by collaboration features.  
When the `database` was used as `COLLABORATION_STORAGE_DRIVER`, there was a problem to run the On-Premises server properly.
* Fixed tooltips display in Management Panel.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-45">

#### Other changes

* Allowed to pass database SSL certificate using `base64` encoded string.  
For some cloud hosting providers like `Azure` or `AWS`, there was a problem with passing database SSL certificate as a one-liner where new lines was represented by a newline character `\n`.  
Therefore, support for SSL certificates provided in `base64` format has been added.  
Encode certificate to `base64` string using `Node.js` example:  
```  
  const fs = require( 'fs' );  
  const certificate = fs.readFileSync( 'path/to/certificate.pem' );  
  console.log( 'base64 encoded certificate:', certificate.toString( 'base64' ) );  
```  
You can also encode certificate to `base64` format using online tools.
* Improved token validation error messages.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--361-2020-08-19">

### 3.6.1 (2020-08-19)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-19">

#### Bug fixes

* Set `DATABASE_DRIVER` configuration variable as optional with `mysql` as default value.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--360-2020-08-13">

### 3.6.0 (2020-08-13)

Due to the change in the structure of the application file tree, for customers who run applications using Node.js instead of Docker images,  
we highly recommend using the “Very safe” method of upgrading to a new version of On-Premises server.  
See [Upgrading to a new version - very safe](https://ckeditor.com/docs/cs/latest/onpremises/cs-onpremises/installation/nodejs.html#very-safe) for more details.

For customers who run applications using Node.js instead of Docker images, please make sure you installed dependencies for Chrome.  
See [Software prerequisites](https://ckeditor.com/docs/cs/latest/onpremises/cs-onpremises/installation/nodejs.html#software-prerequisites) for more details.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-38">

#### Features

* Added import and export feature as an alternative to the autosave plugin.  
This feature allows saving and loading the current collaboration data using server to server communication.
* Added documents storage feature as the next alternative to the autosave plugin.  
This feature allows permanently save the collaboration data in the On-Premises server.
* Added operation history compression as optimization for connection to collaboration.  
This feature can be enabled or disabled for the selected environment using Management Panel.
* Added REST API for Track Changes feature.
* Added queues system based on Redis.  
In queues built on Redis approach, events are emitted to the Redis so other On-Premises server instances can receive events.  
This feature has been added to ensure correct queuing of demanding operations such as document storage or import and export features.
* Improved performance of token validation.
* Improved the performance of user session refreshing.
* Allowed updating names of environments and access keys using Management REST API.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-20">

#### Bug fixes

* Fixed communication protocol used in Management Panel.  
If `APPLICATION_EXTERNAL_ENDPOINT` has been specified then is used for base API address in Management Panel, otherwise, protocol from `x-forwarded-proto` header is used.  
It fixes `Could not establish connection.` error which occurs when connection to Management Panel has been established using HTTPS protocol.
* Increased time for authentication.  
Fixed `Connection hasn't been authenticated in a period of time` error.  
Due to different CKEditor usage on client-side sometimes there was a situation where the client-side was not able to send authentication request in a specific period of time because of a lack of resources like CPU.  
There may also be delays in communicating with the database on server-side.  
To avoid failing to authenticate, this time has been increased.
* Added token refreshing on reconnecting to collaboration.  
Fixed `Connection hasn't been authenticated in a period of time.` error which happens after the browser has been idle for some time.  
This fix is available in the new version of the client API library.
* Shortened connect time for documents with huge `initOperations` data.  
This fix is available in the new version of the client API library.
* Fixed `Cannot access '_0x104788' before initialization` error which was thrown when a problem with the connection to the database occurs.
* Introduced comments deletion which were added to the removed suggestion.
* Fixed performance problem with logging large data/buffers.
* Allowed for graceful Redis failover.
* Added reconnect on MySQL failover.  
This is useful especially when the MySQL failover (e.g. Amazon RDS) is based on DNS and the Writer address needs to be resolved again.
* Added error handling for errors that can occur during GIFs upload.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-46">

#### Other changes

* Added minor UI improvements and fixes for Management Panel.
* Added to Management Panel new view which allows users to manage such features as document storage and history compression.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--350-2020-04-01">

### 3.5.0 (2020-04-01)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-39">

#### Features

* Added UI improvements to the management panel.  
Changed the misleading green color of buttons to red while prompting for removing. Added spinners to indicate long API requests.
* Added checking of database privileges.  
At start-up, the application checks if it has all the database permissions to eliminate all situations when some scripts cannot be executed due to the lack of permissions which may cause a problem with data inconsistencies and errors.
* Added a database reporter.  
Added the ability to generate reports with the database status. Reports are useful for diagnosing database-related problems. MySQL reports include states of migrations, database schema (tables, columns, and indexes), privileges of the current user and system variables. PostgreSQL reports include only migration states.  
The command to generate the report:  
```  
docker run \
  --network=docker_default \
  -e DATABASE_DRIVER=mysql \
  -e DATABASE_HOST=mysql-database \
  -e DATABASE_USER=root \
  -e DATABASE_PASSWORD=password \  
  docker.cke-cs.com/cs:3.5.0 \  
  node ./dist/index.js --database-report > report.md  
```

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-21">

#### Bug fixes

* Disabled rate limiter.  
Disabled rate limiter which in some cases generated the “Too many requests” error.  
For on-premises installations, rate limiter is not very useful because the number of users is usually known.  
By default, rate limiter is disabled but it can be set up using these configuration variables:

  * `RATE_LIMITER_LIMIT` \- The number of tokens at the beginning and the maximum number of tokens which can be collected.
  * `RATE_LIMITER_RENEW_AMOUNT` \- The number of tokens that will be added to the pool every `RATE_LIMITER_RENEW_TIME`.
  * `RATE_LIMITER_RENEW_TIME` \- The time of renewing tokens.  
Rate limiter is based on the leaky bucket algorithm and is separate for each user and connection.
* Fixed a problem with connecting anonymous users.  
It is possible for users to connect to the system without a given ID. In this case, every user is treated as anonymous.
* Improved token validation user experience.  
In the event of problems with the token validation, more accurate error information is returned.
* Fixed an internal problem with serializing messages.  
In quite rare situations, there were internal errors related to message serialization.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-47">

#### Other changes

* Removed unused triggers and columns from the comments table.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--341-2020-02-17">

### 3.4.1 (2020-02-17)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-22">

#### Bug fixes

* Fixed performance.  
Fixed the significant performance decrease from version 3.4.0.
* Improved backward compatibility for JWT tokens that match RFC 7519.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--340-2020-02-13">

### 3.4.0 (2020-02-13)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-40">

#### Features

* Added support for SSL SQL connections.  
CKEditor Cloud Services now supports secure connections to SQL databases. It is possible to connect to databases using an SSL connection with custom SSL certificates.
* Added support for JWT tokens that match RFC 7519.  
The JWT standard specifies some predefined claims like `aud` (audience), `exp` (expiration time), `sub` (subject) or `iat` (issued at). CKEditor Cloud Services uses `aud` for identifying environments, `iat` for checking if the token has not expired and `sub` for identifying users.
* Simplified REST API for comments (v3).  
Endpoints for REST API are unified. You can now filter comments to get or delete by filters in request query parameters like `document_id` or `thread_id`.
* Changed the URL endpoint in REST API for sessions (v3).  
Changed `/documents/{document_id}/users` to `/collaborations/{document_id}/users`.
* Added improvements to the management panel login view.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-23">

#### Bug fixes

* Fixed a problem with numeric user ID.  
Previously, the user ID had to be specified in the token as a string. This problem was resolved and the user ID can also be a number.
* Improved the mechanism for hiding the access key in the management panel.
* Fixed a bug with sending the restore event on a comment or suggestion creation.
* Updated the UI of the REST API documentation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-48">

#### Other changes

* Added support for Python 3.  
Python 2.7 is no longer maintained. Added support for Python 3\. This change applies only to applications launched with Node.js, not Docker.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--330-2020-01-15">

### 3.3.0 (2020-01-15)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-41">

#### Features

* Added support for Node 12.  
CKEditor Cloud Services now works with Node 12, which significantly improved the application performance and security. Image Docker uses Node 12.
* Added support for PostgreSQL database.  
CKEditor Cloud Services On-Premises can work with a MySQL or PostgreSQL database.
* Added support for a few new drivers to store images in different locations.  
Added support for a few drivers to store images in different locations (AWS S3, Azure Blob Storage, file system, MySQL) for Easy Image.
* Introduced REST API v2.  
Changed the endpoint addresses and introduced the new REST API documentation. Merged separated documentation into one OpenAPI definition and into one UI. Replaced Swagger UI with Redoc. Introduced versioning to the REST API documentation.
* Introduced a mechanism to remove data related to a removed environment.  
When the environment is removed, all data related to it is removed from databases.
* Improvements in the dashboard.  
Added a message about generating the API Secret. Added a redirect on a wrong or missing signature. A spinner is now shown in the management panel when resending a webhook request lasts long. Added support for webhook responses without a status.
* Added support for new features from the new version of the JavaScript API.  
Added a mechanism for getting information about users connected to the comments service. Added support for removing a comment thread via the client JavaScript API.
* Encrypted webhook requests history.  
All data related to sent webhook requests is stored in an encrypted form in the database.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-24">

#### Bug fixes

* Improved the performance and stability of the REST API.
* Added cluster connection timeout.
* Mitigated the problem with an anonymous session.  
Improved the mechanism for storing information about users connected to the document.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-49">

#### Other changes

* Removed the `environments-management` console application.  
All management should be done via the web panel or REST API.
* Stored comment content, email and user data in a binary form.  
The data is stored in a binary form, which has improved performance.
* Changed the pagination mechanism for comments and webhooks REST APIs.  
Introduced the pagination method with a cursor.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--320-2019-10-29">

### 3.2.0 (2019-10-29)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-42">

#### Features

* Added the `Management Panel` as a replacement for the `Environments Management` console application.  
See [CKEditor Cloud Services Management Panel](https://ckeditor.com/docs/cs/latest/onpremises/management.html).  
The `Environments Management` console application is deprecated and will be removed in the next version.
* Added the Webhooks feature.  
Webhooks resemble a notification mechanism that can be used to build integrations with CKEditor Cloud Services.  
See [CKEditor Cloud Services Webhooks feature](https://ckeditor.com/docs/cs/latest/onpremises/features/webhooks.html).
* Added REST APIs.  
CKEditor Cloud Services provides full-featured Restful APIs that you can use to create a server-to-server integration.  
See [CKEditor Cloud Services Restful APIs feature](https://ckeditor.com/docs/cs/latest/onpremises/features/apis.html).
* Added an API for CKEditor Cloud Services management (Environments and Webhooks).  
See [Cloud Services Management REST API](https://ckeditor.com/docs/cs/latest/onpremises/management.html).
* The Comments and Suggestions data is now removed permanently when a collaboration session expired.
* The Users and Comments data is now removed permanently during the Environment deletion.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-25">

#### Bug fixes

* Fixed the number validation message for the received data.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-50">

#### Other changes

* Reduced the number of libraries installed required to run CKEditor Cloud Services.
* Improved the data security by adding an initial vector to encrypted data.
* Unified the API request signature.  
See [Creating an environment in Node.js](#cs/latest/examples/on-premises/creating-environment-nodejs.html--example).
* Removed the README.md file from the package.  
From now, the documentation will be available on [CKEditor Ecosystem Documentation - On-Premises](#cs/latest/onpremises/index.html).

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--312-2019-09-02">

### 3.1.2 (2019-09-02)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-43">

#### Features

* Added features which are available in the new version of the client API library.  
Every operation has a metadata object that contains additional information about an operation like information about its author or type.
* Add JWT Token validation.  
Added the token size and token user validation. A more detailed error about token validation failure is now returned. Max token payload size is 2048 bytes. User payload validation rules:  
```  
id    - required (minLength:1, maxLength: 96),  
name  - optional (minLength:1, maxLength: 100),  
email - optional (minLength:3, maxLength: 480),  
```

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-26">

#### Bug fixes

* Fixed the security E2E tests run from a remote machine.
* Fixed the duplicated entry error in track changes.
* Fixed an error with re-adding a comment with the same ID.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-51">

#### Other changes

* Reduced the number of libraries installed required to run CKEditor Cloud Services.
* Add documentation about Docker hardware requirements to README.md.
* Added the expiration time to encryption keys cache.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--311-2019-08-01">

### 3.1.1 (2019-08-01)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-27">

#### Bug fixes

* Set the UTC timezone in the database driver configuration.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-52">

#### Other changes

* Added the `COLLABORATION_EXPIRATION_TIME` variable to the application configuration to allow changing the time after which the document will be deleted when the last user disconnects.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--310-2019-07-30">

### 3.1.0 (2019-07-30)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-44">

#### Features

* Reduced the number of active SQL connections used by the CKEditor Cloud Services application to a single pool of connections.
* Optimized database indices.  
Improved the performance of queries to the SQL database by optimizing table indices after queries execution plan analysis.
* Add the `/health` endpoint to the CKEditor Cloud Services application.  
The `/health` endpoint can be used by a load balancer to discover the availability of your application instances.
* Add input parameters validation.  
Input parameters in a request such as `environmentId`, `userId`, `userEmail`, `sessionId`, `socketId`, `apiVersion`, `documentId` etc. are now validated.
* Added the `application/json` content type as the default header of the HTTP responses.
* Improved the security of the document comments management.
* Added features which will be available with a new version of the client API library.  
The new features will include the possibility to initialize a document as a reader or a commentator as well as will let you assign `authorId` to every document operation made in CKEditor Cloud Services.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-28">

#### Bug fixes

* Fixed errors that occured if a user was disconnected when a document operation was being processed.
* Improved the stability of the event emitting system.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-53">

#### Other changes

* Increased the possible length of `userId` to 96.
* Deleted files that allow for building the Docker image manually.  
Since our Docker images distribution system is ready, we do not recommend to build Docker images manually.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--300-2019-06-28">

### 3.0.0 (2019-06-28)

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--features-45">

#### Features

* Added support for Redis Cluster.  
Increased the ability to scale the application. Added the `REDIS_CLUSTER_NODES` variable to configure the application to use Redis Cluster. See the application configuration or [Docker container environment variables](https://ckeditor.com/docs/cs/latest/onpremises/cs-onpremises/installation/docker.html#docker-container-environment-variables).  
An example of the `REDIS_CLUSTER_NODES` variable:  
```  
[  
  {  
    "host": "127.0.0.1",  
    "port": 7000,  
    "password": "" // optional  
  }  
]  
```
* Added the `MYSQL_PORT` variable to change the default port for MySQL.
* Introduced a new logging system to improve the readability and utility of logs.  
Unified the logs format and introduced a `traceId` to add the possibility to aggregate logs for a specific situation. Improved the performance of the logging system.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--bug-fixes-29">

#### Bug fixes

* Fixed token validation.  
Added a clock tolerance (60 seconds) when checking the creation date of the token. This problem occured when a token was created on a server with an unsynchronized server date.
* Allowed the resizing of images above their original dimensions in Easy Image.
* The EXIF metadata rotation is no longer ignored by Easy Image.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--other-changes-54">

#### Other changes

* Added the possibility to change the protocol to HTTPS in links returned for an uploaded file.  
If the HTTPS protocol is used for uploading and if there is no possibility to configure a load balancer to forward the `X-Forwarded-Proto` and `Host` headers, the application returns URLs with an incorrect protocol.  
Add `APPLICATION_EXTERNAL_ENDPOINT` to the application configuration to force using the HTTPS protocol in links returned for an uploaded file. See [SSL communication](#cs/latest/onpremises/ckbox-onpremises/ssl.html).
* Improved error handling.  
Unified the structure of errors. At this moment, every error has the following fields: `statusCode`, `message`, `data` and `traceId`.
* Optimized the data management algorithm in Redis by replacing `Redis Keyspace Notifications` to a custom implementation.  
The `Redis Keyspace Notifications` feature uses some CPU power which has a huge impact on the application when the number of connected users increases. Also, this solution is not reliable, because it is vulnerable on server restarts.  
At this moment a new, more reliable solution based on a custom implementation of Redis queues was introduced to the application. This solution does not require the `Redis Keyspace Notifications` mechanism.
* Added a cache for Redis scripts.  
Used loaded scripts instead of sending Redis scripts for every operation.

<a id="cs/latest/onpremises/cs-onpremises/changelog.html--breaking-changes">

#### BREAKING CHANGES

* Added the possibility to manage the application from a remote host.  
Added `APPLICATION_ENDPOINT`, removed `CS_CONFIG_PATH` and removed `APPLICATION_HTTP_PORT ` variables in `Environments Management`. See [Environments Management](https://ckeditor.com/docs/cs/latest/guides/environments-management.html).  
The current command to run the `Environments Management`:  
```  
APPLICATION_ENDPOINT=[your_app_endpoint] ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your_env_management_secret_key] node app.js  
```
* Added the possibility to launch tests for the application from a remote host.  
Added `APPLICATION_ENDPOINT ` and removed `APPLICATION_HTTP_PORT` variables. See [Testing the application](#cs/latest/onpremises/cs-onpremises/testing/overview.html).  
The current command to run tests:  
```  
 APPLICATION_ENDPOINT=[your_app_endpoint] ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your_env_management_secret_key] CS_ENV_ID=[environmentId] CS_SECRET_KEY=[secretKey] npm run test  
```
* Removed support for `@ckeditor/ckeditor5-collaboration` version `12.0.1` or older.

<a id="cs/latest/onpremises/cs-onpremises/endpoints.html">source file: "cs/latest/onpremises/cs-onpremises/endpoints.html"</a>

## Setting endpoints

After a successful installation of Collaboration Server On-Premises, you should configure the CKEditor Collaboration web application by setting endpoints that allow for communication between the web application and the server.

* WebSockets endpoint:  
```  
http://localhost[:application_http_port]/ws/  
```
* Token endpoint:  
You should implement your own token endpoint using the data generated in the `Cloud Services Management Panel`. Refer to the [Token endpoint in Node.js](#cs/latest/examples/token-endpoints/nodejs.html) implementation example.
* Panel endpoint:  
```  
http://localhost[:application_http_port]/panel/  
```
* Restful APIs documentation endpoint:  
```  
http://localhost[:application_http_port]/api/v1/docs/  
```
* Health endpoint:  
```  
http://localhost[:application_http_port]/health/  
```  
Very often, a load balancer requires an endpoint to check the application state. For this purpose, it is best to use this endpoint, which returns basic information about the application.

<a id="cs/latest/onpremises/cs-onpremises/features/api-secret.html">source file: "cs/latest/onpremises/cs-onpremises/features/api-secret.html"</a>

## API secret

The API secret is a feature used in many parts of the system.

The difference between the SaaS version and the On-Premises version is management, which results from the use of different dashboard. Below is the instruction on how to manage the API secret in the On-Premises version.

The API secret is available for every environment in the Cloud Services Management Panel. You can find it in the API Configuration section in the details of the environment.

To generate the API secret, click on the `Refresh` button on the right in the `Actions` column.

<a id="cs/latest/onpremises/cs-onpremises/features/apis.html">source file: "cs/latest/onpremises/cs-onpremises/features/apis.html"</a>

## Restful APIs feature

The Restful APIs feature is in the On-Premises version and it is possible to use this feature to build e.g. server-server integration.

The Restful APIs feature has no smaller possibilities than in the SaaS version. However, there is one difference between the versions.

The way to manage the API Secret. This difference is due to the fact that the On-Premises version uses a different dashboard for configuration management than the SaaS version.

Instructions on how to get the API secret in the On-Premises version can be found in the [API secret](#cs/latest/onpremises/cs-onpremises/features/api-secret.html) section.

<a id="cs/latest/onpremises/cs-onpremises/features/overview.html">source file: "cs/latest/onpremises/cs-onpremises/features/overview.html"</a>

## Features overview

The On-Premises version contains all the features of CKEditor Cloud Services available as SasS.

However, there may be some differences between the versions. All differences in operation, management and configuration have been described for the features in which there are differences.

Features where there are differences between the SaaS version and On-Premises:

* [Restul APIs](#cs/latest/onpremises/cs-onpremises/features/apis.html) \- a full-featured Restful APIs you can use to create a server-to-server integration.
* [Webhooks](#cs/latest/onpremises/cs-onpremises/features/webhooks.html) \- a notification mechanism that can be used to build integrations.
* [API secret](#cs/latest/onpremises/cs-onpremises/features/api-secret.html) \- used for authentication in the most critical parts of the system.

<a id="cs/latest/onpremises/cs-onpremises/features/sse-api.html">source file: "cs/latest/onpremises/cs-onpremises/features/sse-api.html"</a>

## Server-side Editor API feature

The Server-side Editor API feature is available in the On-Premises version, and it is possible to use this feature to build deep and complex integration of your application with all document data. It is a part of [the Restful APIs](#cs/latest/onpremises/cs-onpremises/features/apis.html) feature.

The feature is available in the CKEditor Collaboration Server On-premises from version 4.25.0.

The Server-side Editor API feature is enabled by default. However, it requires [the Editor bundle](#cs/latest/guides/collaboration/editor-bundle.html) uploaded to the server.

<a id="cs/latest/onpremises/cs-onpremises/features/sse-api.html--using-the-server-side-editor-api-with-the-external-collaboration-worker">

### Using the Server-side Editor API with the external Collaboration Worker

When the external [Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html) is enabled in the On-Premises environment, the Server-side requests are processed by the worker. As the Server-side Editor API must connect to the Collaboration Server as every other user, providing the `APPLICATION_EXTERNAL_ENDPOINT` environment variable is required. It tells the Collaboration Worker how to connect to the Collaboration Server.

<a id="cs/latest/onpremises/cs-onpremises/features/sse-api.html--security">

### Security

The Server-side Editor API allows performing actions on an editor that is run inside the container. It means that scripts might have access to the internal network. If you are using the Server-side Editor API, you should consider restricting access to the internal network for the containers where the CKEditor Collaboration Server and the CKEditor Collaboration Worker are running. If you are using the CKEditor Collaboration Worker, then all external requests will be made from the Collaboration Worker.

It is highly recommended to set the `EDITOR_API_ACCESS_KEY` environment variable to a random value. Changing this secret improves the security of the Server-side Editor API.

You can read more about the security in the [Security](#cs/latest/developer-resources/server-side-editor-api/security.html) section.

<a id="cs/latest/onpremises/cs-onpremises/features/webhooks.html">source file: "cs/latest/onpremises/cs-onpremises/features/webhooks.html"</a>

## Webhooks feature

The Webhooks feature is in the On-Premises version and it is possible to use this feature to build e.g. integration or notification system.

The Webhooks feature works the same as in the SaaS version. However, there is a difference in configuration management. The configuration described [here](#cs/latest/developer-resources/webhooks/management.html) for the SaaS version may look different than what is available in the On-Premises version. The functionality has not been changed but there may be some slight differences in appearance.

The webhooks management is available for every environment in the Cloud Services Management Panel. You can find it in the Webhooks section in the details of the environment.

<a id="cs/latest/onpremises/cs-onpremises/index.html">source file: "cs/latest/onpremises/cs-onpremises/index.html"</a>

## CKEditor Collaboration Server On-Premises

The On-Premises version of [CKEditor Cloud Services](#cs/latest/guides/overview.html) is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It is a highly scalable solution, designed to handle an unlimited number of concurrent connections. It contains all the features of CKEditor Cloud Services available as SaaS.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/cs-onpremises/overview.html) – An introduction to Collaboration Server On-Premises.
* [Requirements](#cs/latest/onpremises/cs-onpremises/requirements.html) – Learn about the prerequisites to install and run Collaboration Server On-Premises.
* [Installation](#cs/latest/onpremises/cs-onpremises/installation/overview.html) – Learn how to install the Collaboration Server On-Premises using containerization.
* [Management](#cs/latest/onpremises/cs-onpremises/management.html) – Learn how to use the Cloud Services Management Panel or the Cloud Services Management REST API.
* [Testing](#cs/latest/onpremises/cs-onpremises/testing/overview.html) – Learn how to test your Collaboration Server On-Premises installation.
* [Endpoints](#cs/latest/onpremises/cs-onpremises/endpoints.html) – Learn about CKEditor Cloud Services endpoints.
* [Features](#cs/latest/onpremises/cs-onpremises/features/overview.html) – Learn about Collaboration Server On-Premises features.
* [Reverse proxy](#cs/latest/onpremises/cs-onpremises/reverse-proxy.html) – Learn how to set up secure communication with Collaboration Server On-Premises.
* [Logs](#cs/latest/onpremises/cs-onpremises/logs.html) – Learn how to manage logs of Collaboration Server On-Premises.

<a id="cs/latest/onpremises/cs-onpremises/insights-panel.html">source file: "cs/latest/onpremises/cs-onpremises/insights-panel.html"</a>

## Insights panel

The Insights Panel feature allows to gather, list and filter business (audit) logs that come from the server. These logs provide a good insight into what is going on internally in your environments. Also, the Insights Panel serves as a useful debugging tool, especially during integration.

The On-premises variant of tha application contains all the features of the Insights panel as available in the SaaS variant.

The Insights feature can be found in the Management Panel. See the [Insights Panel Guide](#cs/latest/developer-resources/monitoring/insights-panel.html) for instructions on how to turn on the Insights Panel for your environment.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/application-external-endpoint.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/application-external-endpoint.html"</a>

## Overriding external endpoints

Some features, such as the Server-side Editor API, documentation, management panel, or Easy Image, need to recognize the public endpoint where CKEditor Collaboration Server On-Premises is available.

By default, it is determined based on the `HOST` header. To recognize the protocol, the `X-FORWARDED-PROTO` header is used (if the header does not exist, the default protocol is `HTTP`).

Sometimes you may want to set this endpoint manually, for example when `HOST` is overridden by a load balancer or `X-FORWARDED-PROTO` is not provided.

In such cases, you can use the `APPLICATION_EXTERNAL_ENDPOINT` configuration. It should contain the schema (protocol) and host, for example:

```
APPLICATION_EXTERNAL_ENDPOINT=https://example.domain

```

Setting this value is required when using the [Server-side Editor API](#cs/latest/onpremises/cs-onpremises/features/sse-api.html) feature with an [external Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html"</a>

## Collaboration features

Collaboration features are included in the On-Premises server to enable features such as:

* Server-side Editor API,
* document storage,
* import and export,
* connection optimization

Collaboration features offer no lesser capabilities than in the SaaS version. However, they must be properly configured.  
At the moment, Collaboration features support several drivers to store documents and their data in different locations.

There is support for:

* [File system](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--file-system),
* [AWS S3](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--aws-s3),
* [Azure Blob Storage](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--azure-blob-storage),
* [Database](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--database-default).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--reliability">

### Reliability

Collaboration features have high CPU consumption. If you use these features intensively we recommend using an external [CKEditor Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html) to improve reliability.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--configurations">

### Configurations

To configure the collaboration features you need to set the appropriate environment variables.

```
COLLABORATION_STORAGE_DRIVER             - optional (default: "database")
COLLABORATION_STORAGE_LOCATION           - optional (default: "/var/cs/collaboration" if "filesystem" driver chosen, required for file system driver)
COLLABORATION_STORAGE_ACCESS_KEY_ID      - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_SECRET_ACCESS_KEY  - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_REGION             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ENDPOINT           - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_BUCKET             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ACCOUNT_NAME       - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_ACCOUNT_KEY        - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_CONTAINER          - optional (required for Azure Blob Storage driver)
EDITOR_API_ACCESS_KEY                    - optional (recommended when using the Server-side Editor API, must be the same as the one set in the CKEditor Collaboration Server On-premises)

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--database-default">

#### Database (default)

To save the collaboration features data in the SQL database, set the driver only. The documents will be saved as blobs, in a database configured by the database configuration (MySQL and Postgres are supported at the moment).

```
COLLABORATION_STORAGE_DRIVER=database

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--file-system">

#### File system

To save the collaboration features data using the file system, set the (`collaboration_storage_driver`) driver to `filesystem` and specify the (`collaboration_storage_location`) path.

```
COLLABORATION_STORAGE_DRIVER=filesystem
COLLABORATION_STORAGE_LOCATION=/var/cs/documents

```

You should always mount the `/path/to/your/dir:/var/cs/documents` volume to preserve uploaded files in case your container gets removed.

The `COLLABORATION_STORAGE_LOCATION` variable specifies the path to save documents, but this is the path in the container. Therefore, the path to the mounted volume should be given.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--aws-s3">

#### AWS S3

To save the collaboration features data in the AWS S3, set driver (`collaboration_storage_driver`) to `s3` and specify the configuration to AWS S3\. To configure AWS S3, provide data for the following variables:

* `collaboration_storage_region` \- the region to send service requests to,
* `collaboration_storage_access_key_id` \- your AWS access key ID,
* `collaboration_storage_secret_access_key` \- your AWS secret access key,
* `collaboration_storage_endpoint` \- the endpoint URI to send requests to. For example, services compatible with S3 can be used (eg. localstack, etc.). The endpoint must specify its protocol e.g. `s3://`, `https://`, etc.  
By default, it is generated in a format `https://s3.[COLLABORATION_STORAGE_REGION].amazonaws.com`

```
COLLABORATION_STORAGE_DRIVER=s3
COLLABORATION_STORAGE_REGION=[AWS_REGION]
COLLABORATION_STORAGE_ACCESS_KEY_ID=[AWS_ACCESS_KEY_ID]
COLLABORATION_STORAGE_SECRET_ACCESS_KEY=[AWS_SECRET_ACCESS_KEY]
COLLABORATION_STORAGE_BUCKET=[AWS_S3_BUCKET]
COLLABORATION_STORAGE_ENDPOINT=[AWS_S3_ENDPOINT]

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--azure-blob-storage">

#### Azure Blob Storage

To save the collaboration features data in the Azure Blob Storage, set the (`collaboration_storage_driver`) driver to `azure` and specify the configuration to Azure Blob Storage. To configure Azure Blob Storage, provide data for the following variables:

* `collaboration_storage_account_name` \- your Azure account name,
* `collaboration_storage_account_key` \- your Azure account key,
* `collaboration_storage_container` \- your Azure Blob Storage container name.
* `collaboration_storage_endpoint` \- the endpoint URI to send requests to. The endpoint must specify its protocol e.g. `https://`.  
By default, it is generated in a format `https://[COLLABORATION_STORAGE_ACCOUNT_NAME].blob.core.windows.net`

```
COLLABORATION_STORAGE_DRIVER=azure
COLLABORATION_STORAGE_ACCOUNT_NAME=[AZURE_ACCOUNT_NAME]
COLLABORATION_STORAGE_ACCOUNT_KEY=[AZURE_ACCOUNT_KEY]
COLLABORATION_STORAGE_CONTAINER=[AZURE_CONTAINER]
COLLABORATION_STORAGE_ENDPOINT=[AZURE_ENDPOINT]

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html"</a>

## SQL Databases

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--requirements">

### Requirements

SQL database, used by the CKEditor Collaboration Server needs to meet software and hardware requirements presented in the [database requirements](#cs/latest/onpremises/cs-onpremises/requirements.html--databases) article.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--supported-sql-databases">

### Supported SQL databases

The following databases are currently supported:

* PostgreSQL in version 14 (recommended) or 12 (minimal supported version)
* MySQL in version 8.4 (recommended), 8.0 or 5.7 (minimal supported version)

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--driver-selection">

### Driver selection

By default, the MySQL database driver is used.  
It can be changed by using the `DATABASE_DRIVER` environmental variables.

Currently, two options are supported:

* `postgres` \- PostgreSQL
* `mysql` \- MySQL (default)

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--connection-and-basic-credentials">

### Connection and basic credentials

To connect to the database at least the `DATABASE_HOST` needs to be set.  
It is highly recommended to change the default values of the `DATABASE_USER` and `DATABASE_PASSWORD` variables.

```
DATABASE_HOST                            - required
DATABASE_PORT                            - optional (default: 3306)
DATABASE_USER                            - optional (default: "root")
DATABASE_PASSWORD                        - optional (default: "password")
DATABASE_DATABASE                        - optional (default: "cs-on-premises")
DATABASE_SCHEMA                          - optional (default: "cs-on-premises", used for Postgres driver)

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--tls-connection-and-certificates">

### TLS connection and certificates

* If your database server is configured to require SSL connections, you can use `DATABASE_SSL_CA`, `DATABASE_SSL_KEY` and `DATABASE_SSL_CERT` to pass certificates to the database driver.
* If your database server is configured to require SSL connections and the certificate of the database server is signed by a trusted third party, you can set `DATABASE_SSL_ENABLE` to `true` instead of passing the certificates.

```
DATABASE_SSL_ENABLE                      - optional (default: false)
DATABASE_SSL_CA                          - optional
DATABASE_SSL_KEY                         - optional
DATABASE_SSL_CERT                        - optional

```

You can provide the certificates in two ways:

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--passing-certificates-as-files">

#### Passing certificates as files

To pass the certificate as a file you need to provide the path to it, which is available inside of the application container.

```
DATABASE_SSL_CA: /path/to/certificate/server-certificate.pem

```

It may require configuring volumes, to make the certificate available under the path provided to the `DATABASE_SSL_CA` variable.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--passing-certificates-as-text">

#### Passing certificates as text

Another way of providing the required certificates is by providing them as text.

```
DATABASE_SSL_CA: "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----"
DATABASE_SSL_CERT: |
  -----BEGIN CERTIFICATE-----
  MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD
  ...rest_of_certificate_content
  zPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=
  -----END CERTIFICATE-----
DATABASE_SSL_KEY: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVCakNDQXU2Z0F3SUJBZ0lKQU1jMFoKelBXNENYWHZoTG1FMDJUQTkvWmVDdzNLa0hJd2ljTnVFZmE9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

```

The `DATABASE_SSL_CERT` can be provided in three formats:

* as a one-liner, where new lines should be represented by a newline character (\\n).
* in the original certificate format using the Literal Block Scalar character (|).
* as a base64 encoded string. It could solve problems related to newline character encoding by cloud hosting platforms.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--root-certificates-rotation">

#### Root certificates rotation

Various cloud providers e.g. Azure, AWS rotate their root certificates periodically, it may require manual certificate updates by the system administrator to keep the application up and running.

[Read a detailed article about the case in the Azure documentation](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-certificate-rotation)

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--mysql-high-availability">

### MySQL High availability

To ensure high availability of MySQL, we recommend using MySQL Master-Slave Replication with one active master. You can find more information about MySQL replication [here](https://dev.mysql.com/doc/refman/5.7/en/replication.html).

We recommend using one master because the data in the application is modified quickly and it is often the case that the data between nodes is not synchronized due to replication lag.

In case of a failure, the application will not automatically switch between the nodes, so it is worth looking into a load balancer that will automatically turn the connection between the nodes.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--mysql-upgrading-to-version-84">

### MySQL upgrading to version 8.4

MySQL 8.4 deprecates the `mysql_native_password` authentication plugin. It is recommended to use the `caching_sha2_password` plugin instead.  
When the database was created before MySQL 8.0, the `mysql_native_password` plugin was used by default.

In such a case, you will receive the following error:

```
MySQL Error: Plugin 'mysql_native_password' is not loaded"

To run the application with MySQL 8.4, you need to upgrade the database to use the `caching_sha2_password` plugin.

To migrate already existing users to the `caching_sha2_password` plugin, you can use the following SQL commands:

```sql
SELECT user, host, plugin FROM mysql.user ORDER BY user, host;

-- Switch both root accounts (and any app users still on native) to caching_sha2_password:
ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'password';
ALTER USER 'root'@'%'         IDENTIFIED WITH caching_sha2_password BY 'password';

-- Example for other app user:
-- ALTER USER 'app'@'%' IDENTIFIED WITH caching_sha2_password BY 'STRONG_PASSWORD';

FLUSH PRIVILEGES;

-- Verify none remain on native plugin
SELECT user, host, plugin FROM mysql.user WHERE plugin='mysql_native_password';

```

Please note that you need to change the password of the user to the password used to connect to the database by the user.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--next-steps">

### Next steps

* [Read more about SQL Database monitoring](#cs/latest/onpremises/cs-onpremises/resources.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html"</a>

## Easy Image

The Easy Image feature is included in the On-Premises server and it is possible to use this feature to upload and store images.

The Easy Image feature has no smaller possibilities than in the SaaS version. However, it must be properly configured.  
At the moment Easy Image feature supports several drivers to store images in different locations.

There is support for:

* [File system](#cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--file-system-default),
* [AWS S3](#cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--aws-s3),
* [Azure Blob Storage](#cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--azure-blob-storage),
* [Database](#cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--database).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--configurations">

### Configurations

To configure the Easy Image feature you need to set the appropriate environment variables.

```
STORAGE_DRIVER                           - optional (default: "filesystem")
STORAGE_LOCATION                         - optional (default: "/var/cs/easyimage", required for file system driver)
STORAGE_REGION                           - optional (required for AWS S3 driver)
STORAGE_ACCESS_KEY_ID                    - optional (required for AWS S3 driver)
STORAGE_SECRET_ACCESS_KEY                - optional (required for AWS S3 driver)
STORAGE_BUCKET                           - optional (required for AWS S3 driver)
STORAGE_ENDPOINT                         - optional
STORAGE_ACCOUNT_NAME                     - optional (required for Azure Blob Storage driver)
STORAGE_ACCOUNT_KEY                      - optional (required for Azure Blob Storage driver)
STORAGE_CONTAINER                        - optional (required for Azure Blob Storage driver)

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--file-system-default">

#### File system (default)

To save images using the file system, set the (`storage_driver`) driver to `filesystem` and specify the path (`storage_location`).

```
STORAGE_DRIVER=filesystem
STORAGE_LOCATION=/var/cs/easyimage

```

You should always mount volume `/path/to/your/dir:/var/cs/easyimage` to preserve uploaded files in case your container gets removed.

The `STORAGE_LOCATION` variable specifies the path to save images, but this is the path in the container. Therefore, the path to the mounted volume should be given.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--aws-s3">

#### AWS S3

To save images in the AWS S3, set driver (`storage_driver`) to `s3` and specify the configuration to AWS S3\. To configure AWS S3, provide data for the following variables:

* `storage_region` \- the region to send service requests to,
* `storage_access_key_id` \- your AWS access key ID,
* `storage_secret_access_key` \- your AWS secret access key,
* `storage_endpoint` \- the endpoint URI to send requests to. For example, services compatible with S3 can be used (eg. localstack, etc.). The endpoint must specify its protocol e.g. `s3://`, `https://`, etc.  
By default, it is generated in a format `https://s3.[STORAGE_REGION].amazonaws.com`

```
STORAGE_DRIVER=s3
STORAGE_REGION=[AWS_REGION]
STORAGE_ACCESS_KEY_ID=[AWS_ACCESS_KEY_ID]
STORAGE_SECRET_ACCESS_KEY=[AWS_SECRET_ACCESS_KEY]
STORAGE_BUCKET=[AWS_S3_BUCKET]
STORAGE_ENDPOINT=[AWS_S3_ENDPOINT]

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--azure-blob-storage">

#### Azure Blob Storage

To save images in the Azure Blob Storage, set the (`storage_driver`) driver to `azure` and specify the configuration to Azure Blob Storage. To configure Azure Blob Storage, provide data for the following variables:

* `storage_account_name` \- your Azure account name,
* `storage_account_key` \- your Azure account key,
* `storage_container` \- your Azure Blob Storage container name.
* `storage_endpoint` \- the endpoint URI to send requests to. The endpoint must specify its protocol e.g. `https://`.  
By default, it is generated in a format `https://[STORAGE_ACCOUNT_NAME].blob.core.windows.net`

```
STORAGE_DRIVER=azure
STORAGE_ACCOUNT_NAME=[AZURE_ACCOUNT_NAME]
STORAGE_ACCOUNT_KEY=[AZURE_ACCOUNT_KEY]
STORAGE_CONTAINER=[AZURE_CONTAINER]
STORAGE_ENDPOINT=[AZURE_ENDPOINT]

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/easy-image.html--database">

#### Database

To save the images in the SQL database, set the driver only. The images will be saved in a database configured by database configuration.

```
STORAGE_DRIVER=database

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/environmental-variables.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/environmental-variables.html"</a>

## Environmental variables

These are the environment variables used to configure the application when the container is started. The list contains a full set of available environmental variables.

Detailed instructions and explanations can be found in dedicated sections for each part of the configuration. Use the menu on the left side to select the section you are interested in.

```
DATABASE_DRIVER                          - optional (default: "mysql")
DATABASE_HOST                            - required
DATABASE_PORT                            - optional (default: 3306)
DATABASE_USER                            - optional (default: "root"), but it is highly recommended you change it
DATABASE_PASSWORD                        - optional (default: "password"), but it is highly recommended you change it
DATABASE_DATABASE                        - optional (default: "cs-on-premises")
DATABASE_SCHEMA                          - optional (default: "cs-on-premises", used for Postgres driver)
DATABASE_SSL_ENABLE                      - optional
DATABASE_SSL_CA                          - optional
DATABASE_SSL_KEY                         - optional
DATABASE_SSL_CERT                        - optional
REDIS_HOST                               - required
REDIS_PORT                               - optional (default: 6379)
REDIS_DB                                 - optional (default: 1)
REDIS_PASSWORD                           - optional
REDIS_TLS_CA                             - optional
REDIS_TLS_KEY                            - optional
REDIS_TLS_CERT                           - optional
REDIS_TLS_ENABLE                         - optional (default: false)
REDIS_DISABLE_DNS_LOOKUP                 - optional (default: false)
REDIS_CLUSTER_NODES                      - optional
REDIS_IP_FAMILY                          - optional (required only when using an IPv6 domain as `REDIS_HOST` or `REDIS_CLUSTER_NODES`)
APPLICATION_HTTP_PORT                    - optional (default: 8000)
APPLICATION_EXTERNAL_ENDPOINT            - optional (required when using the Server-side Editor API with an external Collaboration Worker)
ENVIRONMENTS_MANAGEMENT_SECRET_KEY       - required
LICENSE_KEY                              - required
COLLABORATION_STORAGE_DRIVER             - optional (default: "database")
COLLABORATION_STORAGE_LOCATION           - optional (default: "/var/cs/collaboration", required for file system driver)
COLLABORATION_STORAGE_ACCESS_KEY_ID      - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_SECRET_ACCESS_KEY  - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_REGION             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ENDPOINT           - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_BUCKET             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ACCOUNT_NAME       - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_ACCOUNT_KEY        - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_CONTAINER          - optional (required for Azure Blob Storage driver)
USE_BUILT_IN_COLLABORATION_WORKER        - optional (default: true)
ENABLE_METRIC_LOGS                       - optional (default: false)
ENABLE_SNAPSHOTS                         - optional (default: true)
EDITOR_API_ACCESS_KEY                    - optional (recommended when using the Server-side Editor API)
MIGRATE_ONLY                             - optional (default: false)

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html"</a>

## In-memory data store

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--requirements">

### Requirements

In-memory data store, used by the CKEditor Collaboration Server needs to meet software and hardware requirements presented in the [database requirements](#cs/latest/onpremises/cs-onpremises/requirements.html--databases) article.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--supported-in-memory-data-stores">

### Supported In-memory data stores

The application requires an in-memory data store compatible with [the Redis protocol](https://redis.io/docs/latest/develop/reference/protocol-spec/).

Supported In-memory data store implementations:

* Valkey - version 9.0.0 or newer (single instance or Cluster mode)
* Redis - version 3.2.6 or newer (single instance or Cluster mode)

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--connecting-to-in-memory-data-store">

### Connecting to in-memory data store

To connect to the in-memory store at least the `REDIS_HOST` needs to be set. Domain names, IPv4 and IPv6 are supported.

```
REDIS_HOST                               - required (for single instance connection)
REDIS_PORT                               - optional (default: 6379)
REDIS_DB                                 - optional (default: 1)
REDIS_PASSWORD                           - optional
REDIS_USER                               - optional
REDIS_IP_FAMILY                          - optional (required only when using an IPv6 domain as `REDIS_HOST`)

```

If you are using a database that only supports IPv6 and you want to refer to that database via its domain name, then the IP version needs to be selected manually.

To do so, you need to set the `REDIS_IP_FAMILY` environment variable to `6`.  
It will force CKEditor Collaboration Server On-Premises to use an IPv6 connection.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--connecting-to-a-cluster">

### Connecting to a cluster

To set up the connection with a Valkey/Redis Cluster, nodes need to be provided as the `REDIS_CLUSTER_NODES` variable.

```
REDIS_CLUSTER_NODES        - required (for Cluster connection)
REDIS_IP_FAMILY            - optional (required only when using an IPv6 domain in `REDIS_CLUSTER_NODES`)

```

The `REDIS_CLUSTER_NODES` needs to contain a list of nodes in the dedicated format, which consists of:

```
"IP:PORT:[optional PASSWORD],IP:PORT:[optional PASSWORD]"

```

To understand the connection string format, check the examples below:

```
# IPv4
REDIS_CLUSTER_NODES: "192.168.0.5:7000,192.168.0.5:7001,192.168.0.5:7002"

# IPv4 with a password
REDIS_CLUSTER_NODES: "192.168.0.5:7000:password1,192.168.0.5:7001:password2,192.168.0.5:7002:password3"

# IPv6
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000,[0:0:0:0:0:0:0:1]:7001,[0:0:0:0:0:0:0:1]:7002"

# IPv6 with a password
REDIS_CLUSTER_NODES: "[0:0:0:0:0:0:0:1]:7000:password1,[0:0:0:0:0:0:0:1]:7001:password2,[0:0:0:0:0:0:0:1]:7002:password3"

# Domain name
REDIS_CLUSTER_NODES: "example.redis.server.com:7000,example.redis.server.com:7001,example.redis.server.com:7002"

# Domain name with IPv6 support
REDIS_IP_FAMILY: 6
REDIS_CLUSTER_NODES: "example.ipv6.redis.server.com:7000,example.ipv6.redis.server.com:7001,example.ipv6.redis.server.com:7002"

# Domain name with a password
REDIS_CLUSTER_NODES: "example.redis.server.com:7000:password1,example.redis.server.com:7001:password2,example.redis.server.com:7002:password3"

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--tls-connection-and-certificates">

### TLS Connection and certificates

* If your in-memory data store server is configured to require SSL connections, you can use `REDIS_TLS_CA`, `REDIS_TLS_KEY`, and `REDIS_TLS_CERT` to pass certificates to the Redis client.
* If you are connecting Collaboration Server On-Premises with an AWS ElastiCache and `Encryption in-transit` is enabled, then you need to set the `REDIS_TLS_ENABLE` environment variable to true. There is no need to pass TLS certificates to make an encrypted connection.
* If you are connecting to AWS ElastiCache Cluster with TLS enabled, you also need to set `REDIS_DISABLE_DNS_LOOKUP` to `true`.

```
REDIS_TLS_CA                             - optional
REDIS_TLS_KEY                            - optional
REDIS_TLS_CERT                           - optional
REDIS_TLS_ENABLE                         - optional (default: false)
REDIS_DISABLE_DNS_LOOKUP                 - optional (default: false)

```

You can provide the certificates in two ways:

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--passing-certificates-as-files">

#### Passing certificates as files

To pass a certificate as a file you need to provide the path to it, which is available inside of the application container.

```
REDIS_TLS_CA: /var/cs/tls/ca.crt
REDIS_TLS_CERT: /var/cs/tls/redis.crt
REDIS_TLS_KEY: /var/cs/tls/redis.key

```

It may require configuring volumes, to make the used files available under the path provided to the `REDIS_TLS_*` variables.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--passing-certificates-as-text">

#### Passing certificates as text

Another way of providing the required certificates is by providing them as text.

```
REDIS_TLS_CA: "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----"
REDIS_TLS_CERT: |
  -----BEGIN CERTIFICATE-----
  MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD
  ...rest_of_certificate_content
  zPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=
  -----END CERTIFICATE-----
REDIS_TLS_KEY: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVCakNDQXU2Z0F3SUJBZ0lKQU1jMFoKelBXNENYWHZoTG1FMDJUQTkvWmVDdzNLa0hJd2ljTnVFZmE9Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

```

The `DATABASE_SSL_CERT` can be provided in three formats:

* as a one-liner, where new lines should be represented by a newline character (\\n).
* in the original certificate format using the Literal Block Scalar character (|).
* as a base64 encoded string. It could solve problems related to newline character encoding by cloud hosting platforms.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--connecting-to-redis-enterprise-cloud">

#### Connecting to Redis Enterprise Cloud

Redis Enterprise Cloud expects users to use the Redis database index of 0\. By default, Collaboration Server On-Premises uses Redis database index 1\. You may thus encounter the `ERR DB index is out of range` error.

To fix it, change the database index using the environment variable:

```
REDIS_DB: 0

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--connecting-to-aws-elasticache">

#### Connecting to AWS ElastiCache

If the AWS ElastiCache is used in Cluster mode then the `clustercfg` url can be provided as one of the nodes in the `REDIS_CLUSTER_NODES` values.

The `REDIS_PASSWORD` value needs to be provided separately.

Example configuration:

```
REDIS_CLUSTER_NODES: clustercfg.redis.xxx.xxx.cache.amazonaws.com:6379
REDIS_PASSWORD: your_password

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--root-certificates-rotation">

#### Root certificates rotation

Various cloud providers e.g. Azure, AWS rotate their root certificates periodically, it may require manual certificate updates by the system administrator to keep the application up and running.

[Read a detailed article about the case in the Azure documentation](https://learn.microsoft.com/en-us/azure/mysql/single-server/concepts-certificate-rotation)

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--in-memory-data-store-high-availability">

### In-memory data store high availability

To ensure high availability of In-memory data store, we recommend using a Cluster mode with at least 3 nodes (must be an odd number of nodes) and using the **master-replica model** in [Valkey](https://valkey.io/topics/replication/) or [Redis](https://redis.io/docs/latest/operate/oss%5Fand%5Fstack/management/scaling/#redis-cluster-master-replica-model), which means that the number of servers increases to 6\. In this configuration, every node should have at least 2 cores and 2 GB of RAM.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html--next-steps">

### Next steps

* [Read more about Redis monitoring](#cs/latest/onpremises/cs-onpremises/resources.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html">source file: "cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html"</a>

## CKEditor Collaboration Worker

The Collaboration Worker is a separate application intended to relieve the CKEditor Collaboration Server On-Premises of high CPU consumptive tasks. Using this service is optional, however it is highly recommended when the [collaboration features](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html) are used.

We recommend using this service in large-scale deployments to improve reliability. If it is possible, you should run this container on a separate machine.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html--scaling">

### Scaling

The only requirement to make the services work together is connecting them to the same Redis and SQL database. You can run multiple worker instances and all of them will be available for Collaboration Server On-Premises instances.

Furthermore, we recommend disabling a built-in Collaboration Worker in Collaboration Server On-Premises if the external is available. You can do it by setting a `USE_BUILT_IN_COLLABORATION_WORKER` environment variable to `false`.

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html--configuration-of-the-ckeditor-collaboration-worker">

### Configuration of the CKEditor Collaboration Worker

The CKEditor Collaboration Worker and the CKEditor Collaboration Server On-Premises should connect to the same databases (SQL and Redis).

The Collaboration storage in both containers should be configured the same way as in the [CKEditor Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html--configurations).

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html--environmental-variables">

#### Environmental variables

```
REDIS_HOST                               - required
REDIS_PORT                               - optional (default: 6379)
REDIS_DB                                 - optional (default: 1)
REDIS_PASSWORD                           - optional
REDIS_USER                               - optional
REDIS_TLS_CA                             - optional
REDIS_TLS_KEY                            - optional
REDIS_TLS_CERT                           - optional
REDIS_TLS_ENABLE                         - optional (default: false)
REDIS_DISABLE_DNS_LOOKUP                 - optional (default: false)
REDIS_CLUSTER_NODES                      - optional
REDIS_IP_FAMILY                          - optional (required only when using an IPv6 domain as `REDIS_HOST` or `REDIS_CLUSTER_NODES`)
COLLABORATION_STORAGE_DRIVER             - optional (default: "database")
COLLABORATION_STORAGE_LOCATION           - optional (default: "/var/cs/collaboration", required for file system driver)
COLLABORATION_STORAGE_ACCESS_KEY_ID      - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_SECRET_ACCESS_KEY  - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_REGION             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ENDPOINT           - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_BUCKET             - optional (required for AWS S3 driver)
COLLABORATION_STORAGE_ACCOUNT_NAME       - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_ACCOUNT_KEY        - optional (required for Azure Blob Storage driver)
COLLABORATION_STORAGE_CONTAINER          - optional (required for Azure Blob Storage driver)
DATABASE_DRIVER                          - optional (default: "mysql")
DATABASE_HOST                            - required
DATABASE_PORT                            - optional (default: 3306)
DATABASE_USER                            - optional (default: "root"), but it is highly recommended you change it
DATABASE_PASSWORD                        - optional (default: "password"), but it is highly recommended you change it
DATABASE_DATABASE                        - optional (default: "cs-on-premises")
DATABASE_SCHEMA                          - optional (default: "cs-on-premises", used for Postgres driver)
DATABASE_SSL_ENABLE                      - optional
DATABASE_SSL_CA                          - optional
DATABASE_SSL_KEY                         - optional
DATABASE_SSL_CERT                        - optional
MIGRATE_ONLY                             - optional (default: false)

```

<a id="cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html--example">

#### Example

* Get familiar with the [example of docker-compose installation with worker](#cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--example-with-collaboration-worker).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html">source file: "cs/latest/onpremises/cs-onpremises/installation/examples/docker.html"</a>

## Docker-compose

For evaluation and testing purposes, you can follow the [Quick-start](#cs/latest/onpremises/cs-onpremises/installation/quickstart.html) guide, where we provide an easy-to-use script for setting up all necessary infrastructure for Collaboration Server On-Premises on your local machine.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--setting-up-the-application-using-the-docker-container">

### Setting up the application using the Docker container

Follow the steps below to install the CKEditor Collaboration Server On-Premises using the Docker container.

1. Use the instructions from the [Customer Portal](https://portal.ckeditor.com/) to log into the `Collaboration Server On-Premises` Docker Registry and pull the Docker image.
2. Containerize the application using [docker](#cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--containerize-example-using-docker) or [docker-compose](#cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--containerize-example-using-docker-compose).
3. Create the `Environment` with an `Access Key` via the [Cloud Services Management Panel](#cs/latest/onpremises/cs-onpremises/management.html). Use this data to [create the token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) and [run tests](#cs/latest/onpremises/cs-onpremises/testing/docker.html).
4. Run tests to verify if the system works properly – see the [Running tests using Docker](#cs/latest/onpremises/cs-onpremises/testing/docker.html) guide.
5. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the Collaboration Server On-Premises application – see the [Setting endpoints](#cs/latest/onpremises/cs-onpremises/endpoints.html) guide.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--containerize-example-using-docker-compose">

### Containerize example using `docker-compose`

Use the steps below to containerize the application using `docker-compose`.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--example-with-mysql">

#### Example with MySQL

1. Create the `docker-compose.yml` file:  
```  
version: "2.2"  
services:  
  mysql-database:  
    image: mysql:8.0.34  
    platform: linux/amd64  
    environment:  
      MYSQL_ROOT_PASSWORD: password  
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro  
    healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.  
      test: ["CMD-SHELL", "exit | mysql -h localhost -P 3306 -u root -p$$MYSQL_ROOT_PASSWORD" ]  
      interval: 10s  
      timeout: 30s  
      retries: 5  
  redis:  
    image: redis:6.2.7  
  ckeditor-cs:  
    image: docker.cke-cs.com/cs:[version]  
    depends_on:  
     redis:  
       condition: service_started  
     mysql-database:  
       condition: service_healthy # Make sure your database is ready for migration.  
    ports:
      - "8000:8000"  
    restart: always  
    init: true  
    environment:  
      DATABASE_HOST: mysql-database  
      DATABASE_USER: root  
      DATABASE_PASSWORD: password  
      REDIS_HOST: redis  
      ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret  
      LICENSE_KEY: your_license_key  
```
2. Create the `init.sql` file:  
```  
CREATE DATABASE `cs-on-premises`  
  DEFAULT CHARACTER SET utf8mb4  
  DEFAULT COLLATE utf8mb4_bin;  
```
3. Run:  
```  
docker-compose up  
```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--example-with-postgresql">

#### Example with PostgreSQL

1. Create the `docker-compose.yml` file:  
```  
version: "2.2"  
services:  
  postgres-database:  
    image: postgres:12.12  
    environment:
      - POSTGRES_PASSWORD=password  
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro  
    healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.  
      test: pg_isready -U postgres  
      interval: 10s  
      timeout: 30s  
      retries: 5  
  redis:  
    image: redis:6.2.7  
  ckeditor-cs-postgres:  
    image: docker.cke-cs.com/cs:[version]  
    depends_on:  
     redis:  
       condition: service_started  
     postgres-database:  
       condition: service_healthy # Make sure your database is ready for migration.  
    ports:
      - "8000:8000"  
    restart: always  
    init: true  
    environment:  
      DATABASE_DRIVER: postgres  
      DATABASE_HOST: postgres-database  
      DATABASE_PORT: 5432  
      DATABASE_USER: postgres  
      DATABASE_PASSWORD: password  
      DATABASE_DATABASE: cksource  
      DATABASE_SCHEMA: cke-cs  
      REDIS_HOST: redis  
      ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret  
      LICENSE_KEY: your_license_key  
```
2. Create the `init.sql` file:  
```  
CREATE DATABASE "cksource";  
\connect "cksource";  
CREATE SCHEMA "cke-cs";  
```
3. Run:  
```  
docker-compose up  
```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--example-with-collaboration-worker">

#### Example with Collaboration Worker

The steps are similar to in the case of regular CKEditor Collaboration Server On-Premises installation.

1. If you have the `docker-compose.yml` file already, you can only add the `worker-cs` service and set the `USE_BUILT_IN_COLLABORATION_WORKER` environment variable to `false` in `ckeditor-cs`. Otherwise, create the file with the following content:

```
version: "3.7"
services:
  mysql-database:
    image: mysql:8.0.34
    platform: linux/amd64
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.
      test: ["CMD-SHELL", "exit | mysql -h localhost -P 3306 -u root -p$$MYSQL_ROOT_PASSWORD" ]
      interval: 10s
      timeout: 30s
      retries: 5

  redis:
    image: redis:6.2.7

  ckeditor-cs:
    image: docker.cke-cs.com/cs:[version]
    depends_on:
      redis:
        condition: service_started
      mysql-database:
        condition: service_healthy # Make sure your database is ready for migration.
    ports:
      - "8000:8000"
    restart: always
    init: true
    environment:
      DATABASE_DRIVER: mysql
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      REDIS_HOST: redis
      ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret
      LICENSE_KEY: your_license_key
      USE_BUILT_IN_COLLABORATION_WORKER: "false"

  worker-cs:
    image: docker.cke-cs.com/cs-worker:[version]
    depends_on:
      redis:
        condition: service_started
      mysql-database:
        condition: service_healthy # Make sure your database is ready for migration.
    restart: always
    init: true
    environment:
      DATABASE_DRIVER: mysql
      DATABASE_HOST: mysql-database
      DATABASE_USER: root
      DATABASE_PASSWORD: password
      REDIS_HOST: redis

```

1. Create the `init.sql` file:  
```  
  CREATE DATABASE `cs-on-premises`  
  DEFAULT CHARACTER SET utf8mb4  
  DEFAULT COLLATE utf8mb4_bin;  
```
2. Run:  
```  
docker-compose up  
```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--notes">

#### Notes

* Use environment variables to configure the application. See the [environmental variables](#cs/latest/onpremises/cs-onpremises/installation/configuration/environmental-variables.html) guide.
* You should override the `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` variable using a unique and hard to guess string due to security reasons.
* The application will not start without a correct `LICENSE_KEY`
* If you use collaboration features (like document storage, import and export, or connection optimizer) intensively, we recommend using [Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html) to improve reliability.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/docker.html--containerize-example-using-docker">

### Containerize example using `docker`

Launch the Docker container:

```
docker run --init -p 8000:8000 -e DATABASE_HOST=[your_mysql_host] -e DATABASE_USER=[your_mysql_user] -e DATABASE_PASSWORD=[your_mysql_password] -e REDIS_HOST=[your_redis_host] -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/cs:[version]

```

Notes:

* Use environment variables to configure the application. See the [configuration guide](#cs/latest/onpremises/cs-onpremises/installation/overview.html). Examples:  
  * If an SQL database and Redis are hosted on `192.168.118.27`, you should pass the address through the `DATABASE_HOST` and `REDIS_HOST` variables:  
  ```  
  docker run --init -p 8000:8000 -e DATABASE_HOST=192.168.118.27 -e REDIS_HOST=192.168.118.27 -e DATABASE_USER=root -e DATABASE_PASSWORD=root_password -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/cs:[version]  
  ```
  * If you want to change the port on which the application will be served to `5000`, override the `APPLICATION_HTTP_PORT` variable and change exposed ports:  
  ```  
  docker run --init -p 5000:5000 -e APPLICATION_HTTP_PORT=5000 -e DATABASE_HOST=192.168.118.27 -e REDIS_HOST=192.168.118.27 -e DATABASE_USER=root -e DATABASE_PASSWORD=root_password -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/cs:[version]  
  ```
* You should override the `ENVIRONMENTS_MANAGEMENT_SECRET_KEY` variable using a unique and hard to guess string due to security reasons.
* The application will not start without a correct `LICENSE_KEY`.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html">source file: "cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html"</a>

## Kubernetes with Helm

The presented example uses Helm charts, if you haven’t used the tool before, we highly recommend getting familiar with the [Helm quick-start docs](https://helm.sh/docs/intro/quickstart/).

The Helm chart setups the basic scenario of the CKEditor Collaboration Server On-Premises in Kubernetes with MySQL database and Redis cluster in two instances without the CKEditor Collaboration Worker.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html--prerequisites">

### Prerequisites

Helm v3 and Kubernetes 1.19+ are required to run examples from the section.

To fetch a Git repository with a pre-configured Helm chart, `git` needs to be installed.

To fetch required docker images you will need to authorize to the CKEditor Collaboration Server On-Premises Docker Registry.  
Please prepare the token from the [Customer Portal](https://portal.ckeditor.com/).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html--preparing-development-environment">

### Preparing development environment

1. Clone the `cksource/ckeditor-cs-on-premises-infrastructure` Git repository.

```
git clone git@github.com:cksource/ckeditor-cs-on-premises-infrastructure.git

```

1. Go to the `ckeditor-cs-development-stack` directory.

```
cd ckeditor-cs-on-premises-infrastructure/kubernetes/helm/ckeditor-cs-development-stack

```

1. Create `imagePullSecret` for pulling images from the CKEditor container registry, replace the `xxx` with the authentication token.

```
kubectl create secret docker-registry docker-cke-cs-com \
    --docker-username "cs" \
    --docker-server "https://docker.cke-cs.com" \
    --docker-password="xxx"

```

1. Install all necessary dependencies. It will download all images needed in further tutorials.

```
helm repo add bitnami https://raw.githubusercontent.com/bitnami/charts/archive-full-index/bitnami &&
helm repo update &&
helm dependency update

```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html--running-the-default-scenario">

### Running the default scenario

The base scenario runs the application with a MySQL and single instance of Redis.

You will need to replace the `xxx` with your CKEditor Collaboration Server On-premises license key, which can be found in [the Customer Portal](https://portal.ckeditor.com/).

```
helm install ckeditor-cs . \
   --set ckeditor-cs.server.secret.data.LICENSE_KEY="xxx"

```

then expose the CKEditor Collaboration Server On-premises port

```
kubectl port-forward service/ckeditor-cs-server 8000

```

**Note: This is not a production-ready solution. To expose the application to the public in a production environment use a proper proxy configuration.**

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html--deleting-installation">

### Deleting installation

The command below will stop and remove all pods which were started during the tutorial.

```
helm delete ckeditor-cs

```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/kubernetes.html--customizing-scenario">

### Customizing scenario

You can adjust the example configuration to your needs by modifying the `values.yaml` file in the `.../kubernetes/helm/ckeditor-cs/` directory.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html">source file: "cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html"</a>

## Installation with Node.js - Not recommended

For evaluation and testing purposes, you can follow the [Quick-start](#cs/latest/onpremises/cs-onpremises/installation/quickstart.html) guide, where we provide an easy-to-use script for setting up all necessary infrastructure for Collaboration Server On-Premises on your local machine.

This approach is **not recommended**. Please use the Docker approach if possible.

Click here to show the Node.js instructions anyway. 

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--setting-up-the-application-directly-on-the-server">

### Setting up the application directly on the server

**Note:** This approach to installing the application is more complicated and requires many dependencies. Therefore, the recommended way to install Collaboration Server On-Premises is to use Docker. See [Setting up the application using the containerization](#cs/latest/onpremises/cs-onpremises/installation/overview.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--requirements">

### Requirements

For every 250 concurrent users, Collaboration Server On-Premises requires 1 additional core of CPU and 500MB of RAM.

* 1 core and 500 MB RAM support up to 250 concurrent users.
* 2 cores and 1 GB RAM support up to 500 concurrent users.
* 4 cores and 2 GB RAM support up to 1,000 concurrent users.
* 8 cores and 4 GB RAM support up to 2,000 concurrent users.
* 16 cores and 8 GB RAM support up to 4,000 concurrent users.

These calculations allow you to run Collaboration Server On-Premises without having to set up load balancers.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--software-prerequisites">

### Software prerequisites

In order to install Collaboration Server On-Premises on the application server, the following software must be installed on the server first:

* `node.js` – version 14.x.  
Download it from: <https://nodejs.org/en/download/package-manager/>
* `pnpm` – version 4.3.x:  
```  
npm i pnpm@4.3.0 -g  
```
* `pm2` – version 3.2.2 or newer:  
```  
npm i pm2 -g  
```
* `libpng-dev`:  
```  
sudo apt install libpng-dev  
```
* `python` – version 3.x is recommended, version 2.7 is deprecated
* `gcc` – version 4.9.x or newer
* `make`
* `autoconf` – 2.69 or newer
* `libtool` – 2.4.2 or newer
* `pkg-config` – 0.26 or newer
* `nasm` – 2.10.09 or newer
* dependencies for Chrome

On Ubuntu you can install `gcc` and `make` with `build-essential`:

```
sudo apt install build-essential

```

To install Chrome dependencies on Ubuntu you can use the following command:

```
sudo apt install libgbm-dev gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--problem-with-node-gyp">

#### Problem with `node-gyp`

In case of problems with `node-gyp`, please check the [node-gyp installation guide](https://github.com/nodejs/node-gyp#installation).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--installation">

### Installation

Unpack the installation package on the Application Server.

1. Set execution permissions on the `setup.sh` file.
2. Run:  
```  
sh setup.sh  
```

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--running-the-application">

### Running the application

1. Create the configuration file `config.json` in a safe place and fill it with your configuration data. See the [configuration example](#cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--configuration-example).
2. Configure the logs directory — see [Logs](#cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--logs).
3. Go to `app/`.
4. Run:  
```  
CS_CONFIG_PATH=[path/to/your/config] pm2 start  
```  
By default the application will be run using all available CPUs but it can be changed by setting the `CS_INSTANCES` variable:  
```  
CS_INSTANCES=1 CS_CONFIG_PATH=[path/to/your/config] pm2 start  
```
5. Check PM2 logs to verify if the application starts properly:  
```  
pm2 logs cs  
```
6. Create the `Environment` with a `Access Key` via [Cloud Services Management Panel](#cs/latest/onpremises/cs-onpremises/management.html). Use this data to [create the token endpoint](#cs/latest/developer-resources/security/token-endpoint.html) and [run tests](#cs/latest/onpremises/cs-onpremises/testing/nodejs.html).
7. Run tests to verify if the system works properly — see [Running tests without Docker](#cs/latest/onpremises/cs-onpremises/testing/nodejs.html).
8. Configure the server endpoints in the CKEditor Collaboration web application to communicate with the Collaboration Server On-Premises application — see [Setting endpoints](#cs/latest/onpremises/cs-onpremises/endpoints.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--application-management">

### Application management

We recommend using PM2 software for application management. Below you can find a list of some of the most important commands:

* `pm2 restart cs` – Restarts all processes of the application.
* `pm2 reload cs` – Reloads all processes of the application, 0-seconds downtime.
* `pm2 logs cs --lines 1000000` – Streams the logs file.
* `pm2 scale cs <number>` – Scales the number of processes up or down.
* `pm2 delete cs all` – Removes all processes.
* `pm2 list` – Lists all processes.
* `pm2 -h` – Help.

Please ensure that you have all needed privileges to use needed PM2 commands.  
More information can be found in the [PM2 documentation](http://pm2.keymetrics.io/docs/usage/quick-start/).

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--configuration-example">

### Configuration example

```
{
    "database_driver": "mysql",                                // optional (default: "mysql")
    "database_host": "127.0.0.1",                              // required
    "database_port": "3306",                                   // optional (default: 3306)
    "database_user": "root",                                   // optional (default: "root"), but it is highly recommended you change it
    "database_password": "password",                           // optional (default: "password"), but it is highly recommended you change it
    "database_database": "cs-on-premises",                     // optional (default: "cs-on-premises")
    "database_schema": "cs-on-premises",                       // optional (default: "cs-on-premises", used for Postgres driver)
    "database_ssl_enable": "",                                 // optional
    "database_ssl_ca": "",                                     // optional
    "database_ssl_key": "",                                    // optional
    "database_ssl_cert": "",                                   // optional
    "redis_host": "localhost",                                 // required
    "redis_port": 6379,                                        // optional (default: 6379)
    "redis_db": 1,                                             // optional (default: 1)
    "redis_password": "",                                      // optional
    "redis_user": "",                                          // optional
    "redis_tls_ca": "",                                        // optional
    "redis_tls_key": "",                                       // optional
    "redis_tls_cert": "",                                      // optional
    "redis_tls_enable": false,                                 // optional (default: false), set to true when connecting to AWS ElastiCache with TLS enabled
    "redis_disable_dns_lookup": false,                         // optional (default: false), set to true when connecting to AWS ElastiCache Cluster with TLS enabled
    "redis_cluster_nodes": "",                                 // optional
    "application_http_port": 8000,                             // optional (default: 8000)
    "application_external_endpoint": "",                       // optional
    "environments_management_secret_key": "secret",            // optional (default: "secret"), but it is highly recommended you change it
    "license_key": "your_license_key",                         // required
      "migrate_only": false,                                     // optional (default: false)
    "collaboration_storage_driver": "database",                // optional (default: "database")
    "collaboration_storage_location": "/var/cs/collaboration", // optional (default: "/var/cs/collaboration", required for file system driver)
    "collaboration_storage_access_key_id": "",                 // optional (required for AWS S3 driver)
    "collaboration_storage_secret_access_key": "",             // optional (required for AWS S3 driver)
    "collaboration_storage_region": "",                        // optional (required for AWS S3 driver)
    "collaboration_storage_endpoint": "",                      // optional (required for AWS S3 driver)
    "collaboration_storage_bucket": "",                        // optional (required for AWS S3 driver)
    "collaboration_storage_account_name": "",                  // optional (required for Azure Blob Storage driver)
    "collaboration_storage_account_key": "",                   // optional (required for Azure Blob Storage driver)
    "collaboration_storage_container": "",                     // optional (required for Azure Blob Storage driver)
    "use_built_in_collaboration_worker": true,                 // optional (default: true)
    "enable_metric_logs": false                                // optional (default: false)
}

```

Notes:

* Please save you configuration **outside the application package directory**. This prevents from overwriting your configuration during the application update process.
* Without a correct `license_key` the application will not start.
* Example of `redis_cluster_nodes` variable:  
```  
[  
  {  
    "host": "127.0.0.1",  
    "port": 7000,  
    "password": "", // optional  
    "user": "" // optional  
  },  
  {  
    "host": "127.0.0.1",  
    "port": 7001,  
    "password": "", // optional  
    "user": "" // optional  
  },  
  {  
    "host": "127.0.0.1",  
    "port": 7002,  
    "password": "", // optional  
    "user": "" // optional  
  }  
]  
```
* If your database server is configured to require SSL connections, you can use `database_ssl_ca`, `database_ssl_key` and `database_ssl_cert` to pass certificates to the database driver. You can pass certificates directly with certificate content or as `path/to/certificate.crt`. Example:  
```  
{  
  "database_ssl_ca": "-----BEGIN CERTIFICATE-----\nMIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD\nVQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi\n............\nzPW4CXXvhLmE02TA9/ZeCw3KkHIwicNuEfa=\n-----END CERTIFICATE-----",  
  "database_ssl_cert": "/var/cs/ssl/client-certificate.pem"  
}  
```
* If your database server is configured to require SSL connections and the certificate of the database server is signed by a trusted third party, you can set `DATABASE_SSL_ENABLE=true` instead of passing the certificates.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--configuring-the-database">

### Configuring the database

At the moment the following databases are supported:

* MySQL in version 8.4 (recommended), 8.0 or 5.7 (minimal supported version).
* PostgreSQL in version 14 (recommended) or 12 (minimal supported version)

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--mysql">

#### MySQL

MySQL is selected as default so you do not need to explicitly specify this driver. Example configuration:

```
{
    "database_host": "127.0.0.1",
    "database_port": "3306",
    "database_user": "root",
    "database_password": "password",
    "database_database": "cs-on-premises",
    "database_ssl_ca": "server-certificate-content or path/to/server-certificate.crt",
    "database_ssl_key": "client-key-content or path/to/client-key.key",
    "database_ssl_cert": "client-certificate-content or path/to/client-certificate.crt",

    // ...
}

```

The values above are examples and should be changed.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--postgresql">

#### PostgreSQL

To use PostgreSQL you have to set `database_driver` to `postgres`. Example configuration:

```
{
    "database_driver": "postgres",
    "database_host": "127.0.0.1",
    "database_port": "5432",
    "database_user": "postgres",
    "database_password": "password",
    "database_database": "cksource",
    "database_schema": "cs-on-premises",
    "database_ssl_ca": "server-certificate-content or path/to/server-certificate.crt",
    "database_ssl_key": "client-key-content or path/to/client-key.key",
    "database_ssl_cert": "client-certificate-content or path/to/client-certificate.crt",

    // ...
}

```

The values above are examples and should be changed.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--logs">

### Logs

Make sure that write permissions are granted for the logs directory.

By default all logs are stored in the `/var/log/cs/cs.log` file but it is strongly recommended to change this location by using the `CS_LOGS_PATH` variable:

```
CS_LOGS_PATH=[path/to/logs] CS_CONFIG_PATH=[path/to/your/config] pm2 start

```

Set `CS_LOGS_PATH` **outside the application package directory**. This prevents from unwanted changes in your logs made during the application update process.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--generating-a-startup-script">

### Generating a startup script

See <http://pm2.keymetrics.io/docs/usage/startup/>.

<a id="cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--upgrading-to-a-new-version">

### Upgrading to a new version

1. Install the software prerequisites if some versions have changed or if new ones have been added — see [Software prerequisites](#cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--software-prerequisites).
2. Unzip the package with a new version to a separate directory, for example: `new_version_dir`.
3. Check the [changelog](#cs/latest/onpremises/cs-onpremises/changelog.html) for breaking changes and adjust the configuration if needed.
4. Create a new test SQL database or schema (if you are using a PostgresSQL database) and use it in the configuration file. See the `database_database` variable for MySQL or `database_schema` variable for PostgresSQL — refer to the [Configuring the database](#cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--configuring-the-database) section.
5. Change the Redis database in the configuration file to the one that is not used in the currently running application — see the `redis_db` variable.
6. Change `application_http_port` to some free port that is not used in the currently running application.
7. Go to `new_version_dir` and run the installation — see [Installation](#cs/latest/onpremises/cs-onpremises/installation/examples/nodejs.html--installation).
8. Go to `new_version_dir/app` and start the test application:  
```  
CS_CONFIG_PATH=[path/to/your/config] pm2 start src/index.js --name test_cs  
```
9. Run tests — see [Running tests without Docker](#cs/latest/onpremises/cs-onpremises/testing/nodejs.html).
10. If the new version of the application works properly, shut it down:

```
pm2 delete test_cs

```

1. Change `database_database`/`database_schema` and `redis_db` to the previous values used in the application.
2. Change `application_http_port` to the previous port used in the application.
3. Go to `new_version_dir/app/`.
4. Stop the current version of the application and run the new version:

```
pm2 delete all && pm2 kill && CS_CONFIG_PATH=[path/to/your/config] pm2 start

```

1. Verify if everything is working correctly.
2. If yes, you can delete the previous version. If not, stop the new version and run the previous version again.

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html">source file: "cs/latest/onpremises/cs-onpremises/installation/overview.html"</a>

## Installation overview

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--supported-technologies">

### Supported technologies

The application is provided as a docker image by default.

It can be run with any Open Container runtime tool e.g. [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

Refer to the [Requirements guide](#cs/latest/onpremises/cs-onpremises/requirements.html) for more information about the hardware and software requirements to run Collaboration Server On-Premises.

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--sandbox-on-premises-setup">

### Sandbox On-Premises setup

For evaluation and testing purposes, you can follow the [Quick-start](#cs/latest/onpremises/cs-onpremises/installation/quickstart.html) guide, where we provide an easy-to-use script for setting up all necessary infrastructure for Collaboration Server On-Premises on your local machine.

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--configuration">

### Configuration

Articles in this section provide information about the possibilities and instructions on how to configure the application depending on the user’s needs.

* [SQL Database](#cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html) \- stores permanent data
* [In-memory data store](#cs/latest/onpremises/cs-onpremises/installation/configuration/in-memory-store.html) \- stores temporary data
* [Collaboration features](#cs/latest/onpremises/cs-onpremises/installation/configuration/collaboration.html) \- includes document storage, import and export, and connection optimization.
* [Overriding external endpoint](#cs/latest/onpremises/cs-onpremises/installation/configuration/application-external-endpoint.html) \- overrides public endpoint

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--production-deployment">

### Production deployment

Production deployment can differ for every use case, so it is hard to determine one approach which will suit every case.  
In a dedicated article, you will find a list of scripts prepared to run basic scenarios using different tools and platforms.  
It can be used as a base to prepare a production-ready setup.

Check the [Production deployment article](#cs/latest/onpremises/cs-onpremises/installation/production-deployment.html)

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--performance-and-reliability">

### Performance and reliability

The performance of the CKEditor Collaboration Server On-Premises depends on many factors. It is heavily related to the features used, specific use cases, and the type of content of processed documents. Some features like document storage, import and export, or connection optimizer are highly CPU-consumptive tasks. The CKEditor Collaboration Server can not only be scaled, but also separate workers for specific, CPU-consuming tasks can be set up.

To enable and configure separate CKEditor Collaboration Worker check [the dedicated article](#cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html).

You can read more about the CKEditor Collaboration Server On-Premises performance in [the Requirements article](#cs/latest/onpremises/cs-onpremises/requirements.html--hardware-requirements).

<a id="cs/latest/onpremises/cs-onpremises/installation/overview.html--support">

### Support

[Contact us](https://ckeditor.com/contact/) if you have any questions about the installation process or would like to customize the recommended setup.

<a id="cs/latest/onpremises/cs-onpremises/installation/production-deployment.html">source file: "cs/latest/onpremises/cs-onpremises/installation/production-deployment.html"</a>

## Production deployment

To reduce the time needed to set up a production-ready environment, the most common configuration was prepared in the form of ready-to-use examples.

Presented examples configure a basic environment and they can be easily used as a base to prepare extended, production setup.

<a id="cs/latest/onpremises/cs-onpremises/installation/production-deployment.html--aws-ecs">

### AWS ECS

Use this script to provision infrastructure with recommended settings and install CKEditor Collaboration Server on your AWS account.

[AWS ECS configuration](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/aws/ecs)

<a id="cs/latest/onpremises/cs-onpremises/installation/production-deployment.html--azure-aks">

### Azure AKS

Use these Terraform modules to provide infrastructure hosted in Microsoft Azure for CKEditor Collaboration Server On-Premises. There are two modules: one for provisioning the infrastructure needed to run the service, and the other for deploying the service onto that infrastructure.

[Azure AKS configuration](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/azure/aks)

<a id="cs/latest/onpremises/cs-onpremises/installation/production-deployment.html--kubernetes-with-helm-charts">

### Kubernetes with Helm charts

Use this Helm chart to provide CKEditor Collaboration Server on your Kubernetes cluster.

This Helm chart deploys only the CKEditor Collaboration Server and requires an externally provisioned SQL database and Redis instance.

[See our Helm Charts](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/kubernetes/helm)

<a id="cs/latest/onpremises/cs-onpremises/installation/production-deployment.html--next-steps">

### Next steps

* [Read more about application monitoring](#cs/latest/onpremises/cs-onpremises/request-summary.html).

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html">source file: "cs/latest/onpremises/cs-onpremises/installation/quickstart.html"</a>

## Quick start installation guide

The Collaboration Server On-Premises Quick-Start guide lets you quickly set up the infrastructure needed to use CKEditor 5 with Real-Time Collaboration and Collaboration Server On-Premises. With a single setup command you can run a working CKEditor 5 instance and start testing our solution, with the Collaboration Server running locally on your machine. This setup process should take less than 10 minutes (it may be slightly longer in case of a slow network connection).

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--prerequisites">

### Prerequisites

To successfully run Collaboration Server On-Premises Quick-Start you need the following tools:

* **Docker Desktop** for Windows or Mac (or Docker tools for Linux)
* **node** version 10 and above
* **npm** version 6 and above
* **git**

If you do not have these tools installed on your machine, refer to the following installation guides:

* The [Docker Desktop on Win10 installation guide](https://docs.docker.com/docker-for-windows/install/)
* The [Docker Desktop on Mac installation guide](https://docs.docker.com/docker-for-mac/install/)
* The [Node.js download page](https://nodejs.org/en/)
* The [Git installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

The On-Premises Quick-Start installation will download several docker images about 2GB in size. Appropriate free space on your disk is hence required.

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--getting-credentials">

### Getting credentials

Two essential credentials are needed to run the Collaboration Server On-Premises Quick-Start: a License key and a Download token, both available through the [Customer Portal](https://portal.ckeditor.com/).

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--step-1-get-your-download-token">

#### Step 1: Get your Download token

1. Log in to the [Customer Portal](https://portal.ckeditor.com/)
2. Navigate to **Subscription → License keys → Collaboration**
3. Scroll to the _Download token_ section
4. If no tokens exist, click **Create token**
5. Copy and save the token

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--step-2-get-your-license-key">

#### Step 2: Get your License key

Your next steps depend on your license type:

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--option-a-online-license-recommended">

##### Option A: Online License (Recommended)

For the **Online** license version, you should see the License key value right away as shown below.

**Benefits of Online License:** The online license offers automatic scaling with no hard user limits, allowing your collaboration needs to grow naturally. You benefit from simplified management as there’s no need to pre-allocate users or manage complex allocation pools. This flexible usage model grows with your team without hitting hard stops that could interrupt your workflow. Most importantly, there’s no risk of blocking users - when you exceed limits, you’re billed accordingly rather than users being prevented from collaborating.

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--option-b-offline-license">

##### Option B: Offline License

With the **Offline** license version, you receive an **allocation pool** representing your total Annual and Concurrent users. This allows you to create multiple individual license keys from this pool.

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--understanding-the-allocation-pool-for-offline-licenses">

###### Understanding the allocation pool for offline licenses

Your allocation pool contains the total Annual and Concurrent users you purchased. You create individual license keys by allocating users from this pool. Understanding the two user types is essential for proper allocation:

* **Annual users** represent the maximum number of unique users who can use the collaboration features within a 12-month period with your specific key
* **Concurrent users** define the maximum number of users who can actively collaborate simultaneously at any given moment

For example, if you create a key with 50 Annual users and 10 Concurrent users, only 50 unique people can use collaboration features per year, with a maximum of 10 people collaborating at the same time.

When your entire allocation pool is used up across all created keys, you cannot create additional license keys. To increase your pool or get additional licenses, you need to submit a support request, either through the Customer Portal or through the [contact us](https://ckeditor.com/contact/) form. Your existing keys will continue to work normally within their allocated limits.

To manage your allocation effectively, plan your key allocation strategy before creating keys, considering separate allocations for development, staging, and production environments. Consider future growth when allocating users to each key to avoid running out of capacity. Monitor your usage regularly to avoid hitting limits unexpectedly, and contact support well in advance if you anticipate needing additional capacity.

**To create a license key:**

1. Click **Create license key**
2. Allocate Annual and Concurrent users from your pool
3. Add a descriptive label for identification
4. Confirm by clicking **Create license key**

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--setup-steps">

### Setup steps

1. Make sure that Docker Desktop is running. You can check the Docker tray icon to see the current status.
2. Verify that you have all the necessary tools installed by running this command in your terminal:

```
docker -v && docker-compose -v && node -v && npm -v && git --version

```

You should see version numbers of all of these tools. If you see a `command not found` message, please install the missing tool before proceeding with the next step.

1. Clone [repository](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure) containing script files and install the packages with the following commands:

```
git clone https://github.com/cksource/ckeditor-cs-on-premises-infrastructure.git

cd ckeditor-cs-on-premises-infrastructure/quick-start && npm install

```

1. Run the On-Premises Quick-Start, replacing the arguments with the credentials placeholders with your credentials:

```
node setup.js --license_key="YOUR_LICENSE_KEY" --docker_token="YOUR_DOCKER_DOWNLOAD_TOKEN" --env_secret="YOUR_ENVIRONMENT_SECRET"

```

Use the values obtained from the [Customer Portal](https://portal.ckeditor.com/). The `env_secret` value is your own password, that will be used to access the Collaboration Server On-Premises [management panel](#cs/latest/onpremises/cs-onpremises/management.html)

**Running this setup process for the first time may take several minutes.** The script needs to pull several docker images from the web, install the packages and build the editor bundle. The following command runs will be much shorter. After the successful installation, you should see a message stating `Visit http://localhost:3000 to start collaborating`. Open this page in your browser.

When your testing session is over, you can simply stop running the process in the terminal with the `Ctrl+C` keystroke and the created containers will be removed from your machine.

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--setupjs-arguments">

### setup.js arguments

Only the 3 arguments mentioned above are required to successfully run the Collaboration Server On-Premises Quick-Start script. There are, however, other optional arguments to customize the setup process. Here is a list of all possible arguments:

```
--license_key=""      - required,
--docker_token=""     - required,
--env_secret=""       - required,
--docker_endpoint=""  - optional, the default is "docker.cke-cs.com", use it to change the docker registry url
--version=""          - optional, the default is "latest", use it to specify a different version of the docker image
--cs_port=""          - optional, the default is "8000", a port for Collaboration Server On-Premises
--node_port=""        - optional, the default is "3000", a port for the frontend part of Quick-Start
--keep_containers     - optional, use it to preserve the created containers on exit

```

**Note:** If you use different ports than the default ones, please remember to update the URL endpoints after opening a sample page.

<a id="cs/latest/onpremises/cs-onpremises/installation/quickstart.html--next-steps">

### Next steps

* [Check detailed information on how to setup the CKEditor Collaboration Server On-Premises depending on your needs.](#cs/latest/onpremises/cs-onpremises/installation/overview.html)
* [Check ready to use scripts that will prepare a basic, production ready setup.](#cs/latest/onpremises/cs-onpremises/installation/production-deployment.html)

<a id="cs/latest/onpremises/cs-onpremises/license-usage.html">source file: "cs/latest/onpremises/cs-onpremises/license-usage.html"</a>

## License

<a id="cs/latest/onpremises/cs-onpremises/license-usage.html--license-usage">

### License usage

Checking the current license usage can be done by clicking the “License” button in the top-right corner of the Management Panel.

A modal with license details will appear.

The information displayed on a modal can differ depending on the type of license.

You can display a list of users counted into the usage by clicking into the displayed usage, for example, `8/20`.

Read more about billing in the [Billings](#cs/latest/developer-resources/security/token-endpoint.html--billings) section.

<a id="cs/latest/onpremises/cs-onpremises/license-usage.html--billings">

### Billings

The On-Premises variant of the CKEditor Collaboration Server is limited by the number of unique connected users.

A unique user is counted based on a unique pair of the aud(environment ID) and sub(user ID) properties from the token. In the case of an anonymous user, every user will be billed separately, as a random user ID will be assigned.

Read more about users in the [User](#cs/latest/developer-resources/security/token-endpoint.html--user) section.

<a id="cs/latest/onpremises/cs-onpremises/logs.html">source file: "cs/latest/onpremises/cs-onpremises/logs.html"</a>

## Logs and monitoring

The logs in Collaboration Server On-Premises are written to `stdout` and `stderr`. Most of them are formatted in JSON. They may be used for debugging purposes or for monitoring requests rate, errors, duration and warnings (invalid requests). In production environments, we recommend storing logs to files or using a distributed logging system (like ELK or CloudWatch).

<a id="cs/latest/onpremises/cs-onpremises/logs.html--docker">

### Docker

Docker has built-in logging mechanisms that capture logs from the output of containers. The default logging driver writes logs to files.

When using this driver, you can use the `docker logs` command to show logs from the container. You can add the `-f` flag to view logs in real time. Refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/logs/) for more information about the `logs` command.

<a id="cs/latest/onpremises/cs-onpremises/logs.html--log-level">

#### Log level

Every log contains the `level` property. Log levels help to determine importance of a log.

The CKEditor Collaboration Sever groups logs into 6 levels:

* `10` \- Trace - Most granular information about processes taking place in the application,
* `20` \- Debug - Logs added temporarily to monitor hard-to-debug cases,
* `30` \- Info - Information about modification of a resource or audit logs,
* `40` \- Warn - Usually they can be ignored because they were caused the asynchronous nature of processing events in the application. They may also inform you that some process failed the first time, but another attempt solved the problem. If they appear simultaneously with errors `log level: ≥50`, they can speed up the debugging of the problem by giving more context,
* `50` \- Error - Indicates that some process has been stopped unexpectedly or does not work properly,
* `60` \- Fatal - Errors that cause the entire application to stop working.

By default, only logs with `level=40` and above are printed out.  
The default setting can be changed by setting the `LOG_LEVEL=[value]` environmental variable.  
It is not recommended to set the value under 40, as it may generate huge amount of logs. Depending on your setup it may lead to performance or memory issues.

<a id="cs/latest/onpremises/cs-onpremises/logs.html--distributed-logging">

### Distributed logging

If you are running more than one instance of Collaboration Server On-Premises, it is recommended to use a distributed logging system. It allows you to view and analyze logs from all instances in one place.

<a id="cs/latest/onpremises/cs-onpremises/logs.html--aws-cloudwatch-and-other-cloud-solutions">

#### AWS CloudWatch and other cloud solutions

If you are running Collaboration Server On-Premises in the cloud, the simplest and recommended way is to use a service which is available at the selected provider. Some of the available services include:

* AWS – [CloudWatch](https://aws.amazon.com/CloudWatch)
* Google Cloud – [Cloud Logging](https://cloud.google.com/logging)
* Azure – [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor)

To use CloudWatch with AWS ECS, you have to create a log group first and change the log driver to `awslogs`. When the log driver is configured properly, the logs will be streamed directly to CloudWatch.

The `logConfiguration` of logging may look similar to this:

```
"logConfiguration": {
  "logDriver": "awslogs",
  "options": {
    "awslogs-region": "us-west-2",
    "awslogs-group": "cksource",
    "awslogs-stream-prefix": "ck-cs-logs"
  }
}

```

Refer to the [Using the awslogs Log Driver](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using%5Fawslogs.html) article for more information.

<a id="cs/latest/onpremises/cs-onpremises/logs.html--on-premises-solutions">

#### On-Premises solutions

If you are using your own infrastructure or for some reason cannot use the service offered by your provider, you can always use some on-premises distributed logging system.

There are a lot of solutions available, including:

* [ELK](https://www.elastic.co/what-is/elk-stack) \+ [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html)  
This is a stack built on top of Elasticsearch, Logstash and Kibana. In this configuration, Elasticsearch stores the logs, Filebeat reads the logs from Docker and sends them to Elasticsearch, and Kibana is used to view them. Logstash is not necessary because the logs are already structured.
* [Fluentd](https://www.fluentd.org/)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/fluentd) to send logs. It has a built-in frontend, but can be also integrated with Elasticsearch and Kibana for better filtering.
* [Graylog](https://www.graylog.org)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/gelf) to send logs. It has a built-in frontend and needs Elasticsearch to store logs as well as a MongoDB database to store the configuration.

<a id="cs/latest/onpremises/cs-onpremises/logs.html--example-configuration">

##### Example configuration

The example configuration uses Fluentd, Elasticsearch and Kibana to capture logs from Docker.

Before running Collaboration Server On-Premises, you have to prepare the logging services. For the purposes of this example, Docker Compose is used. Create the `fluentd`, `elasticsearch` and `kibana` services inside the `docker-compose.yml` file:

```
version: '3.7'
services:
  fluentd:
    build: ./fluentd
    volumes:
      - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
    ports:
      - "24224:24224"
      - "24224:24224/udp"

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
    expose:
      - 9200
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:6.8.5
    environment:
      ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
    ports:
      - "5601:5601"

```

To integrate Fluentd with Elasticsearch, you first need to install `fluent-plugin-elasticsearch` in the Fluentd image. To do this, create a `fluentd/Dockerfile` with the following content:

```
FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
    && gem install fluent-plugin-elasticsearch \
    && gem sources --clear-all

```

Next, configure the input server and connection to Elasticsearch in the `fluentd/fluent.conf` file:

```
<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>
<match *.**>
  @type copy
  <store>
    @type elasticsearch
    host elasticsearch
    port 9200
    logstash_format true
    logstash_prefix fluentd
    logstash_dateformat %Y%m%d
    include_tag_key true
    type_name access_log
    tag_key @log_name
    flush_interval 1s
  </store>
  <store>
    @type stdout
  </store>
</match>

```

Now you are ready to run the services:

```
docker-compose up --build

```

When the services are ready, you can finally start Collaboration Server On-Premises.

```
docker run --init -p 8000:8000 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
docker.cke-cs.com/cs:[version]

```

Now open Kibana in your browser. It is available at <http://localhost:5601/>. In the first run, you may be asked about creating an index. Use the `fluentd-*` pattern and press the “Create” button. After this step, your logs should appear in the “Discover” tab.

<a id="cs/latest/onpremises/cs-onpremises/management.html">source file: "cs/latest/onpremises/cs-onpremises/management.html"</a>

## Cloud Services Management

You can manage the environments in Collaboration Server On-Premises using the `Cloud Services Management Panel` or via `Cloud Services Management REST API`.

<a id="cs/latest/onpremises/cs-onpremises/management.html--cloud-services-management-panel">

### Cloud Services Management Panel

<a id="cs/latest/onpremises/cs-onpremises/management.html--features">

#### Features

The `Cloud Services Management Panel` application can be used to:

* Create, modify and delete environments.
* Add an access key to an existing environment or remove it.
* Manage webhooks configuration.
* Manage API Secret.
* Check license usage.

<a id="cs/latest/onpremises/cs-onpremises/management.html--running">

#### Running

The `Cloud Services Management Panel` is available at `/panel/`. So if the application is launched on `localhost` on `8000` port, the panel is available at `http://localhost:8000/panel/`.

<a id="cs/latest/onpremises/cs-onpremises/management.html--usage">

#### Usage

Managing environments through the `Cloud Services Management Panel` is possible immediately after starting the application. You only need to enter the secret on the first screen to allow communication between the panel and the application.

After logging in, the first screen with a list of environments with manageability is visible.

Details of each environment with the possibility of configuration changes, key management, etc. are available after entering the selected environment.

<a id="cs/latest/onpremises/cs-onpremises/management.html--security">

#### Security

The secret provided at login is stored for an hour, after this time you have to enter the secret again. However, the `Cloud Services Management Panel` is built into the application and is available at `/panel/`. That is why we recommend adding authentication to the load balancer level for the panel address.

<a id="cs/latest/onpremises/cs-onpremises/management.html--cloud-services-management-rest-api">

### Cloud Services Management REST API

<a id="cs/latest/onpremises/cs-onpremises/management.html--features-2">

#### Features

The `Cloud Services Management REST API` contains the same features as the `Cloud Services Management Panel` but does not provide a web interface. However, can be useful for automating environmental management via scripts.

<a id="cs/latest/onpremises/cs-onpremises/management.html--running-2">

#### Running

The `Cloud Services Management REST API` consists of two APIs. One API is used to manage environments and its documentation can be found at `/environments/docs`. The second, separate API is used to manage the webhooks configuration and documentation can be found at `/webhooks/docs`.

<a id="cs/latest/onpremises/cs-onpremises/management.html--usage-2">

#### Usage

The `Cloud Services Management REST API` can be used immediately after starting the application. However, please note that every request has to have an authorization header.

Read more about authorization in the [Security](#cs/latest/onpremises/cs-onpremises/management.html--security-2) section.

<a id="cs/latest/onpremises/cs-onpremises/management.html--security-2">

#### Security

Each request sent to `Cloud Services Management REST API` should have authorization headers (`X-CS-Signature` and `X-CS-Timestamp`). This is the same algorithm as the one for [restful APIs](#cs/latest/developer-resources/apis/overview.html) described [here](#cs/latest/developer-resources/security/request-signature.html).

Check an [example of using the API to create an environment with an authorization header in Node.js](#cs/latest/examples/on-premises/creating-environment-nodejs.html).

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html">source file: "cs/latest/onpremises/cs-onpremises/nightly-releases.html"</a>

## Nightly releases

This article describes the purpose and usage of nightly releases of CKEditor Collaboration Server On-Premises images.

Nightly images are released every day. During the automatic release, we run our tests to make sure that these images are working correctly, but unlike stable releases, nightly builds do not go through our full release process and are not tested and approved by our Quality Assurance.

Nightly images include all of the changes that are merged on our development branches. This allows you to access new features or receive fixes faster than with stable on-premises images.

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html--dangers-of-using-nightly-builds">

### Dangers of using nightly builds

Nightly builds are released automatically. By the nature of these images, they should be treated as unstable. Running an On-Premises application using these images may result in some unexpected behaviors, undocumented features or known and unknown defects.

You need to ensure that the versions that you are willing to run are working correctly and will not impact your application negatively. We highly recommend using DEV/UAT environments first and going through the process of quality acceptance on your side, before you use nightly images in production.

By using the nightly builds you accept the risks mentioned in the documentation.

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html--nightly-images-usage">

### Nightly images usage

There is a difference between the usage of nightly and stable releases of CKEditor Collaboration Server On-Premises. Instead of the `cs` image, you should use the `cs-nightly` images. Notice that the version of nightly images also includes a date and a hash. This date part can help you find the latest version of the nightly build. Example usage:

```
version: "2.2"
services:
    cs-nightly:
        image: docker.cke-cs.com/cs-nightly:4.17.1-20240227-a846c6d954 # change the version
        ports:
        - "8000:8000"
        # environment variables and other configuration

```

Nightly builds are available only as docker images.

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html--list-of-available-nightly-versions">

### List of available nightly versions

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html--nightly-versions">

<a id="cs/latest/onpremises/cs-onpremises/nightly-releases.html--fetching-the-latest-nightly-version">

### Fetching the latest nightly version

If you want to automate the process of updating your application and automatically use the latest versions of nightly builds you can make a GET request at <https://docker.cke-cs.com/api/versions/cs-nightly>. This will fetch the JSON with all available versions. Use the date in the version to find the latest image that can be used in your application.

<a id="cs/latest/onpremises/cs-onpremises/overview.html">source file: "cs/latest/onpremises/cs-onpremises/overview.html"</a>

## Collaboration Server On-Premises

The documentation in this section refers to a simplified version of Collaboration Server On-Premises which was designed to be easy to set up and maintain (while preserving all features). It also lowers the running costs by reducing the number of servers required to run the whole application to the minimum.

If your usage scenario involves running Collaboration Server On-Premises for more than 50,000 concurrent connections, please [contact us](https://ckeditor.com/contact/) to discuss the most optimal setup for your needs.

The Collaboration Server On-Premises installation requires two servers: one for running the application (“Application Server”) and another one for hosting the databases (“Database Server”). Refer to the [Requirements guide](#cs/latest/onpremises/cs-onpremises/requirements.html) for more information.

<a id="cs/latest/onpremises/cs-onpremises/overview.html--next-steps">

### Next steps

Read [how to install Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/installation/overview.html).

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html">source file: "cs/latest/onpremises/cs-onpremises/request-summary.html"</a>

## Requests logging

To get more insight into how the Collaboration Server is performing, we built logs that can be used for monitoring. To enable these, just add the `ENABLE_METRIC_LOGS=true` environment variable.

These are logs (metrics) that are always logged with `level = 30` (even if the request returns an error). They are printed for all synchronous requests (HTTP and WebSockets). In the case of these logs, you must rely on the `status` or `statusCode` properties to detect any anomaly.

Meaning of statuses:

* `success` – request responses with status codes `<399`
* `warning` – request responses with status codes `≥400` and `<499`
* `fail` – request responses with status codes `≥500`

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--log-structure">

### Log structure

The log structure contains the following information:

* `handler` – A unified identifier of action. Use this field to identify calls.
* `traceId` – A unique RPC call ID.
* `tags` – A semicolon-separated list of tags. Use this field to filter metrics logs.
* `data` – An object containing additional information. It might vary between different transports.
* `data.duration` – The request duration in milliseconds.
* `data.transport` – The type of the request transport. It could be `http` or `ws` (websocket).
* `data.status` – The request status. It can be equal to `success`, `fail`, `warning`.
* `data.statusCode` – The response status in the HTTP status code standard.

Additionally, for the HTTP transport, the following information is included:

* `data.url` – The URL path.
* `data.method` – The request method.

In case of an error, `data.status` will be equal to `failed` and `data.message` will contain the error message.

An example log for HTTP transport:

```
{
  "level": 30,
  "time": "2021-03-09T11:15:09.154Z",
  "msg": "Request summary",
  "handler": "v5:GET:collaborations:id:exists",
  "traceId": "bd77768c-4f49-44da-b658-f765340ea643",
  "data": {
    "duration": 32,
    "transport": "http",
    "statusCode": 200,
    "status": "success",
    "url": "/api/v5/e2e-58a48a5ba8521b6f/collaborations/e2e-eff1945d39894534/exists",
    "method": "GET"
  },
  "tags": "metrics"
}

```

An example log for WS transport:

```
{
  "level": 30,
  "time": "2021-03-09T13:11:52.068Z",
  "msg": "Request summary",
  "handler": "addComment",
  "traceId": "db09ba44-cb96-4db6-84f0-59eb3691b193",
  "data": {
    "duration": 12,
    "transport": "ws",
    "status": "success",
    "statusCode": 200
  },
  "tags": "metrics"
}

```

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--example-charts">

### Example charts

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--display-number-of-requests-rate-per-transport-type">

#### Display number of requests rate per transport type

This information will give you the overall number of requests handled by the Collaboration Server split by transport (WebSockets and HTTP).

Use the `data.transport` field to distinguish between different request types.

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--display-requests-latency-per-operation">

#### Display requests latency per operation

This chart will show how fast requests are per specific operation, which is very useful for measuring user experience as well as debugging.

Use the `data.duration` and `handler` fields to measure request latency of operations.

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--errors-count-per-operation">

#### Errors count per operation

Display number of failures (5xx codes) per operation type.

Use the `handler` and `data.status` fields to count failures of operations.

<a id="cs/latest/onpremises/cs-onpremises/request-summary.html--warnings-count-per-operation">

#### Warnings count per operation

Display number of warnings (4xx codes) per operation type. This information is very useful especially for debugging the system performance issues.

Use the `data.status` and `data.statusCode` fields to count incorrect requests and their types.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html">source file: "cs/latest/onpremises/cs-onpremises/requirements.html"</a>

## Requirements

This article describes the requirements that need to be met for Collaboration Server On-Premises to run smoothly.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--collaboration-server-on-premises">

### Collaboration Server On-Premises

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--hardware-requirements">

#### Hardware requirements

It is impossible to provide a single infrastructure setup, that will fit all use cases. In this section, we provide recommendations for ensuring high availability and high performance of Collaboration Server On-Premises. As every use case is different, you need to monitor your application and adjust the infrastructure to your needs.

The performance of On-Premises is influenced by used features. Currently, we can consider 2 cases:

* basic features related to collaboration on documents,
* features that require an [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html).

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--basic-features-related-to-collaboration-on-documents">

##### Basic features related to collaboration on documents

Basic functions such as: creating a document, writing in a document, broadcasting changes to users, adding comments, creating suggestions, or sending webhooks do not require a lot of hardware resources. The performance of the On-Premises server can be defined as the number of simultaneously processed requests per single CPU core.

A single instance of On-Premises running on a server with 1 core can handle 20 requests per second. This number may be different for your use-case and it is recommended to monitor the load and adjust the infrastructure if needed. To measure the number of requests handled by the On-Premises server, you can turn on the [metric logs](#cs/latest/onpremises/cs-onpremises/request-summary.html) section where you can see what requests are processed by the server and check the processing time of these requests (`duration` property).

Based on the observation of the number of requests and the time of their processing, it can be concluded whether the number of On-Premises instances should be increased or changes should be made to other parts of the infrastructure (e.g. databases). Read more about our [recommendations for monitoring logs and resources](#cs/latest/onpremises/cs-onpremises/resources.html).

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--features-that-require-an-editor-bundle">

##### Features that require an editor bundle

Collaboration features (that use an uploaded [editor bundle](#cs/latest/guides/collaboration/editor-bundle.html)) have high CPU consumption. The above-mentioned throughput of 20 requests per second may significantly drop. Therefore, if features that require an editor bundle are used and frequent use of these features is expected, we recommend using the [Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html).

A single instance of Collaboration Worker running on a server with 2CPU and 2GB RAM can handle an average of 30 document conversions per minute. In addition, we recommend that every single instance (docker container) of the Collaboration Worker should be on a dedicated server because 2 instances on the same server will steal each other’s server resources. It means that the number of simultaneous document processing will not be doubled.

The conversion processing time may change depending on what plugins are used in the editor bundle and on the size of the content. Therefore, to provide users with a good experience, it is necessary to monitor the processing time of requests and in the case of delayed times, scale up the Collaboration Worker instances. Read more about our recommendations for monitoring logs and resources [here](#cs/latest/onpremises/cs-onpremises/logs.html).

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--high-availability">

##### High availability

To ensure high availability, we recommend running at least 3 instances of the CKEditor Collaboration Server On-Premises.

CKEditor Collaboration Server On-Premises can be scaled with Docker containers on a single host machine. However, we recommend scaling on at least three host machines to provide the reliability of the system.

A load balancer, like HAProxy or NGINX (see the load balancer configuration examples in the [Reverse proxy](#cs/latest/onpremises/cs-onpremises/reverse-proxy.html) guide), is required for scaling on several machines. Of course, it is possible to use any cloud provider for scaling, such as Amazon ECS, Azure Container Instances, or Kubernetes.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--software-requirements">

#### Software requirements

Currently, we only provide Linux-based Docker images for the CKEditor Collaboration Server. We highly recommend running them on machines with Linux, but you can also use Docker Desktop to run our Docker images on other operating systems.

The application is provided as a docker image by default.

It can be run with any Open Container runtime tool e.g. [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

In the case of Windows machines, you need to enable the [WSL 2](https://docs.microsoft.com/en-us/windows/wsl/about#what-is-wsl-2) backend and switch to Linux containers. Make sure that your operating system supports such an option. Refer to the [Docker Desktop installation guide](https://docs.docker.com/desktop/windows/install/) for more information.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--databases">

### Databases

Information about the requirements for databases.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--hardware-requirements-2">

#### Hardware requirements

The minimum database server requirements (for MySQL and Redis installation) to handle up to 8,000 concurrent users is 2 cores and 4GB of RAM (`a1.large` equivalent on Amazon EC2).

If your installation has to support more than 8,000 users, [contact us](https://ckeditor.com/contact/) to discuss the most optimal hardware setup for your needs.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--containers">

##### Containers

Databases can be launched as containers, but this requires high awareness and responsiveness. Because each company has different policies and arrangements, we do not recommend any approach and leave the decision as to how the databases will be launched for you.

However, we encourage you to read this article [“To run or not to run a database on Kubernetes: What to consider”](https://cloud.google.com/blog/products/databases/to-run-or-not-to-run-a-database-on-kubernetes-what-to-consider) before making a decision.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--software-requirements-2">

#### Software requirements

Requirements for database engines: Valkey/Redis and PostgreSQL/MySQL.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--in-memory-data-store">

##### In-memory data store

The application requires an in-memory data store compatible with the Redis protocol.

* Valkey version 9.0.0 or newer or Redis version 3.2.6 or newer.
* In-memory store keeps all temporary data related to collaboration and is used as a cache. The storage requirements for the In-memory store depend on the number of active documents.
* The average size of one document is around 500KB of memory. This size depends on many factors — the document length, the number of users, the number of changes, etc., and it can grow to many megabytes.
* Use Valkey/Redis Cluster if the application needs to handle a large number of active users. Please [contact us](https://ckeditor.com/contact/) if this is the case.

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--postgresql">

##### PostgreSQL

* PostgreSQL version 14 (recommended) or 12 (minimal supported version)
* The database and user should have at least the following privileges: `SELECT, INSERT, UPDATE, DELETE, REFERENCES, CREATE, USAGE`.
* The database with a schema should be created before running Collaboration Server On-Premises. Example database and schema creation script (for `psql`):  
```  
CREATE DATABASE "cksource";  
\connect "cksource";  
CREATE SCHEMA "cs-on-premises";  
```

<a id="cs/latest/onpremises/cs-onpremises/requirements.html--mysql">

##### MySQL

* Version 8.4 (recommended), 8.0 or 5.7 (minimal supported version).
* Create the database and a user with the following permissions: `ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, TRIGGER, UPDATE, LOCK TABLES, REFERENCES`. Example database creation script:  
```  
CREATE DATABASE `cs-on-premises`  
  DEFAULT CHARACTER SET utf8mb4  
  DEFAULT COLLATE utf8mb4_bin;  
```
* Change the `max_allowed_packet` setting to allow saving blobs for documents storage feature (editor bundles, document content, etc.) in the database:  
```  
set global max_allowed_packet = 209715200;  
```
* From version 8.4, MySQL deprecates the `mysql_native_password` authentication plugin. It is recommended to use the `caching_sha2_password` plugin instead, [see more details](#cs/latest/onpremises/cs-onpremises/installation/configuration/database-sql.html--mysql-upgrading-to-version-84).
* MySQL stores all persistent data like comments, users, environments information, etc. The storage requirements for MySQL depend on many factors.
* If you want to use another SQL database like Microsoft SQL Server, etc., please [contact us](https://ckeditor.com/contact/).

<a id="cs/latest/onpremises/cs-onpremises/resources.html">source file: "cs/latest/onpremises/cs-onpremises/resources.html"</a>

## Monitoring resources

To ensure that the infrastructure for Collaboration Server On-Premises is correctly scaled and can handle the load you need to monitor the following servers:

* **SQL server** – monitor CPU and memory usage

  * If the consumption of these resources reaches 70-90%, consider increasing the size or the number of nodes of the SQL server.
* **Redis server** – monitor CPU and memory usage

  * If the consumption of these resources reaches 70-90%, consider increasing the size or the number of nodes of the Redis server.
* **On-Premises server** – monitor CPU and memory usage, and the processing time of requests from [metric logs](#cs/latest/onpremises/cs-onpremises/request-summary.html)

  * If the consumption of these resources reaches 70-90% or you notice a significant increase of the `duration` values in metric logs:  
    * consider scaling Collaboration Server On-Premises instances if high usage is caused by users and collaboration sessions,
    * consider scaling (or start using) [Collaboration Worker](#cs/latest/onpremises/cs-onpremises/installation/configuration/worker.html) instances if high usage is caused by editor bundle features

Read more about resources requirements in a [dedicated article](#cs/latest/onpremises/cs-onpremises/requirements.html).

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html">source file: "cs/latest/onpremises/cs-onpremises/reverse-proxy.html"</a>

## Reverse proxy / load balancing

Collaboration Server On-Premises can be served by a reverse proxy or a load balancer of your choice. It is required for securing communication to the server by the TLS protocol and for handling the environment at scale. Also, it is a good practice to use a reverse proxy to handle the traffic to the application server. Besides distributing load between the multiple instances of an application, it can be used to secure the connection with WAF or prevent DDOS attacks.

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--requirements">

### Requirements

The WebSocket protocol handles most of the communication between users and Collaboration Server On-Premises. The chosen reverse proxy or load balancer must support the WebSocket protocol.

The `X-Forwarded-Proto` and `Host` headers need to be passed from the reverse proxy to the Collaboration Server On-Premises. These headers are required to handle the generation of uploaded image URLs and to ensure that the Management Panel works correctly.

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--nginx">

### `NGINX`

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--basic-configuration">

#### Basic configuration

```
server {
    listen 80;
    server_name your.domain.name;

    location / {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;

        proxy_pass http://127.0.0.1:8000;
    }
}

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--handling-multiple-instances">

#### Handling multiple instances

```
upstream ckeditor-cs {
    server ckeditor-cs-1.example.com:8000 weight=1;
    server ckeditor-cs-2.example.com:8000 weight=1;
    server ckeditor-cs-3.example.com:8000 weight=1;
}

server {
    listen 80;
    server_name your.domain.name;

    location / {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;

        proxy_pass http://ckeditor-cs;
    }
}

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--encrypting-connection-with-tls">

#### Encrypting connection with TLS

```
server {
    server_name your.domain.name;

    listen 80;

    return 301 https://$host$request_uri;
}

server {
    server_name your.domain.name;

    listen 443;
    ssl on;
    ssl_certificate /etc/ssl/your_cert.crt;
    ssl_certificate_key /etc/ssl/your_cert_key.key;

    location / {
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;

        proxy_pass http://127.0.0.1:8000;
    }
}

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--haproxy">

### `HAProxy`

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--basic-configuration-2">

#### Basic configuration

```
global
    daemon

defaults
    mode http
    timeout connect 5s
    timeout client 120s
    timeout server 120s

frontend http-in
    bind *:80
    http-request set-header X-Forwarded-Proto http

    default_backend servers

backend servers
    server server1 127.0.0.1:8000 check

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--handling-multiple-instances-2">

#### Handling multiple instances

```
global
    daemon

defaults
    mode http
    timeout connect 5s
    timeout client 120s
    timeout server 120s

frontend http-in
    bind *:80
    http-request set-header X-Forwarded-Proto http

    default_backend servers

backend servers
    option httpchk

    server server1 ckeditor-cs-1.example.com:8000 check
    server server2 ckeditor-cs-2.example.com:8000 check
    server server3 ckeditor-cs-3.example.com:8000 check

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--encrypting-connection-with-tls-2">

#### Encrypting connection with TLS

```
global
    daemon
    tune.ssl.default-dh-param 2048

defaults
    mode http
    timeout connect 5s
    timeout client 120s
    timeout server 120s

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/your_certificate.pem
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
    redirect scheme https if !{ ssl_fc }

    default_backend servers

backend servers
    server server1 127.0.0.1:8000

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--caddy">

### `Caddy`

Caddy handles automatic TLS certificates and certificates renewal. Also, it requires no additional configuration for WebSocket connections and passes all required headers automatically.

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--one-liner">

#### One liner

```
$ caddy reverse-proxy --from your.domain.name --to 127.0.0.1:8000

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--basic-configuration-3">

#### Basic configuration

```
your.domain.com {
    reverse_proxy 127.0.0.1:8000
}

```

<a id="cs/latest/onpremises/cs-onpremises/reverse-proxy.html--handling-multiple-instances-3">

#### Handling multiple instances

```
your.domain.com {
    reverse_proxy ckeditor-cs-1.example.com:8000 ckeditor-cs-3.example.com:8000 ckeditor-cs-3.example.com:8000
}

```

<a id="cs/latest/onpremises/cs-onpremises/testing/docker.html">source file: "cs/latest/onpremises/cs-onpremises/testing/docker.html"</a>

## Running tests using Docker

<a id="cs/latest/onpremises/cs-onpremises/testing/docker.html--prerequisites">

### Prerequisites

In order to run tests, Docker should be installed.

<a id="cs/latest/onpremises/cs-onpremises/testing/docker.html--running-tests">

### Running tests

These steps allow you to verify if the application works correctly after the first run or an application update:

1. Use instructions from the [Customer Portal](https://portal.ckeditor.com/) to log into the `Collaboration Server On-Premises` Docker Registry and pull the Docker image.  
```  
docker login -u [user] -p [download_token] [registry]  
docker pull [registry]/cs-tests:[version]  
```
2. Run tests:

2.1\. Normal mode.  
```  
 docker run \
 -e APPLICATION_ENDPOINT="[your_app_endpoint]" \
 -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY="[your_env_management_secret_key]" \  
 [registry]/cs-tests:[version]  
```

2.2\. Parallel mode – A faster approach. In case of errors we recommend to run tests using the normal mode.  
```  
 docker run \
 -e PARALLEL=true \
 -e APPLICATION_ENDPOINT="[your_app_endpoint]" \
 -e ENVIRONMENTS_MANAGEMENT_SECRET_KEY="[your_env_management_secret_key]" \  
 [registry]/cs-tests:[version] -- --max-parallel 6  
```
3. If there are no errors after finishing the tests, the application is ready to use.

Notes:

* `APPLICATION_ENDPOINT` – An endpoint required to communicate with Collaboration Server On-Premises.
* `ENVIRONMENTS_MANAGEMENT_SECRET_KEY `– A variable set in the Collaboration Server On-Premises configuration.
* There is a possibility that some test will not pass. In this case please run the tests again.

<a id="cs/latest/onpremises/cs-onpremises/testing/nodejs.html">source file: "cs/latest/onpremises/cs-onpremises/testing/nodejs.html"</a>

## Running tests without Docker - Not recommended

This approach is **not recommended**. Please use the Docker approach if possible.

Click here to show the Node.js instructions anyway. 

<a id="cs/latest/onpremises/cs-onpremises/testing/nodejs.html--prerequisites">

### Prerequisites

In order to run tests, the following software must be installed first:

* `node.js` – version 14.x:  
Download it from <https://nodejs.org/en/download/package-manager/>.
* `pnpm` – version 4.3.x:  
```  
npm i pnpm@4.3.0 -g  
```

From the [Customer Portal](https://portal.ckeditor.com/), download the software ZIP package that matches the downloaded Docker image. Unzip the package and go to the package root directory.

<a id="cs/latest/onpremises/cs-onpremises/testing/nodejs.html--running-tests">

### Running tests

These steps allow you to verify if the application works correctly after the first run or an application update:

1. Go to `tests/`.
2. Run:  
```  
pnpm install  
```
3. Run:  
```  
APPLICATION_ENDPOINT=[your_app_endpoint] ENVIRONMENTS_MANAGEMENT_SECRET_KEY=[your_env_management_secret_key] npm run test  
```
4. If there are no errors after finishing the tests, the application is ready to use.

Notes:

* `APPLICATION_ENDPOINT` – An endpoint required to communicate with Collaboration Server On-Premises.
* `ENVIRONMENTS_MANAGEMENT_SECRET_KEY `– A variable set in the Collaboration Server On-Premises configuration.
* There is a possibility that some test will not pass. In this case please run the tests again.
* You can run the tests from the server where Collaboration Server On-Premises is installed by setting `APPLICATION_ENDPOINT=http://localhost[:application_http_port]` or from a remote machine by setting `APPLICATION_ENDPOINT=https://your.external.address`.

<a id="cs/latest/onpremises/cs-onpremises/testing/overview.html">source file: "cs/latest/onpremises/cs-onpremises/testing/overview.html"</a>

## Testing overview

There are two ways to test Collaboration Server On-Premises:

* **\[Recommended\]** [Run tests using a Docker image](#cs/latest/onpremises/cs-onpremises/testing/docker.html). We strongly recommend to use Docker images because it does not require installing any additional dependencies.
* [Run tests without Docker](#cs/latest/onpremises/cs-onpremises/testing/nodejs.html). Use this approach if you cannot use Docker. Requires installation of external dependencies.

[Contact us](https://ckeditor.com/contact/) if you have any questions about the testing process.

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html">source file: "cs/latest/onpremises/cs-onpremises/upgrading.html"</a>

## Upgrading the Docker installation

We release a new Collaboration Server On-Premises version every 6 weeks. It comes with new features, bug fixes, and security updates. Some new CKEditor 5 features may not be compatible with older versions of Collaboration Server On-Premises, too. For these reasons, **it is highly recommended to keep your Collaboration Server On-Premises server up-to-date**.

Using Docker containers greatly simplifies the process of upgrading the Collaboration Server On-Premises version. The upgrade process may differ depending on the deployment tools and platforms used. Refer to the steps below for the correct order of actions.

All important changes are added to the Collaboration Server On-Premises [changelog](#cs/latest/onpremises/cs-onpremises/changelog.html). You can find it in the [Customer Portal](https://portal.ckeditor.com/).

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html--upgrading-to-a-new-version-fast">

### Upgrading to a new version – fast

The approach described here requires upgrading Collaboration Server to version 4.14.0 or newer. If you plan to upgrade to an older version, please follow the [zero downtime](#cs/latest/onpremises/cs-onpremises/upgrading.html--upgrading-to-a-new-version-zero-downtime) approach.

This approach is recommended if you can accept a temporary downtime of Collaboration Server On-Premises. The advantage of this approach is faster upgrading time as you can upgrade from a very old version way faster than in the [zero downtime](#cs/latest/onpremises/cs-onpremises/upgrading.html--upgrading-to-a-new-version-zero-downtime) approach. The disadvantage of this approach is that we recommend disabling Collaboration Server On-Premises for the time of the upgrade. Operating on Collaboration Server On-Premises during the upgrade in this approach causes a risk of data inconsistency or application errors.

1. **Backup your database** – this will ensure that in the case of any issues after the upgrade you can restore the database and roll back to the previously used Collaboration Server On-Premises version.
2. Stop all instances of the Collaboration Server On-Premises servers.
3. Run a new instance of the Collaboration Server On-Premises servers using the latest available version.
4. Verify whether the Collaboration Server On-Premises servers are up and running.

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html--upgrading-to-a-new-version-zero-downtime">

### Upgrading to a new version – zero downtime

Use this approach in situations where any downtime of the Collaboration Server On-Premises services is not acceptable. The drawback of this approach is the longer update time. The described approach is also recommended if you plan to migrate to Collaboration Server version 4.13.0 or older. The method is based on the blue/green deployment approach that can be easily introduced to solutions based on [Kubernetes](https://kubernetes.io/blog/2018/04/30/zero-downtime-deployment-kubernetes-jenkins/#blue-green-deployment) or dedicated services such as [AWS ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-blue-green.html).

1. Configure your infrastructure to proxy all traffic only to healthy Collaboration Server On-Premises instances. The configuration can rely on the results from the `/health` endpoint.
2. **Backup your database** – this will ensure that in the case of any issues after the upgrade you can restore the database and roll back to the previously used Collaboration Server On-Premises version. Backing up your DB after each upgrade will allow you to roll back only one minor version, in case when some upgrade went wrong.
3. Next to the currently working application, start the Collaboration Server On-Premises servers using a higher minor version – **you should NOT skip any minor versions when upgrading**. For example, if you are currently running Collaboration Server On-Premises version 3.12 and you would like to upgrade it to the latest version, you should start with an upgrade to v3.13\. The traffic should not be proxied to the new instance until it will be healthy.
4. Once the new Collaboration Server On-Premises container is up and running (the `/health` endpoint returns a correct status), disable traffic and stop the Collaboration Server On-Premises container in the old version.
5. Repeat steps 2, 3, and 4 until you have the desired version of the Collaboration Server On-Premises running.

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html--migrate-only-mode">

#### Migrate only mode

The `MIGRATE_ONLY` environmental variable allows you to detach upgrading Collaboration Server On-Premises from upgrading the database structure. Once the variable value is set to `true`, the container will stop once the database migration finishes. It will allow you to improve your observability by disabling the healthcheck for the container in the `MIGRATE_ONLY` mode and re-enable it only for an actual application container that uses an already migrated database. As migrating from a very old version may take some time, especially if your database is large, it may happen that the application will not be available in the desired timeout which may cause a healthcheck failure. Detaching migration from an application start prevents the described situation. The `MIGRATE_ONLY` environmental variable is available for Collaboration Server On-Premises version 4.15.0 or newer.

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html--example-container-configuration-for-detached-migration-process-docker-compose">

##### Example container configuration for detached migration process - Docker Compose

```
version: "2.2"
  services:
    mysql-database:
      image: mysql:8.0.34
      platform: linux/amd64
      environment:
        MYSQL_ROOT_PASSWORD: password
      volumes:
        - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
      healthcheck: # Define healthcheck to be able to use the `service_healthy` condition.
        test: ["CMD-SHELL", "exit | mysql -h localhost -P 3306 -u root -p$$MYSQL_ROOT_PASSWORD" ]
        interval: 10s
        timeout: 30s
        retries: 5
    redis:
      image: redis:6.2.7
    ckeditor-cs-migrator:
      image: docker.cke-cs.com/cs:[version]
      depends_on:
        redis:
          condition: service_started
        mysql-database:
          condition: service_healthy # Make sure your database is ready for migration.
      restart: "no" # Migrator should NOT restart when migration is done.
      init: "true"
      environment:
        MIGRATE_ONLY: "true"
        DATABASE_HOST: mysql-database
        DATABASE_USER: root
        DATABASE_PASSWORD: password
        REDIS_HOST: redis
        ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret
        LICENSE_KEY: your_license_key
        STORAGE_DRIVER: filesystem
        STORAGE_LOCATION: /var/cs/easyimage
        LOG_LEVEL: 30
      volumes:
        - ~/easyimage_files:/var/cs/easyimage
    ckeditor-cs:
      image: docker.cke-cs.com/cs:[version]
      depends_on:
        redis:
          condition: service_started
        mysql-database:
          condition: service_healthy
        ckeditor-cs-migrator:
          condition: service_completed_successfully
      ports:
        - "8000:8000"
      restart: always
      init: "true"
      environment:
        DATABASE_HOST: mysql-database
        DATABASE_USER: root
        DATABASE_PASSWORD: password
        REDIS_HOST: redis
        ENVIRONMENTS_MANAGEMENT_SECRET_KEY: secret
        LICENSE_KEY: your_license_key
        STORAGE_DRIVER: filesystem
        STORAGE_LOCATION: /var/cs/easyimage
      volumes:
        - ~/easyimage_files:/var/cs/easyimage

```

<a id="cs/latest/onpremises/cs-onpremises/upgrading.html--example-container-configuration-for-detached-migration-process-aws-ecs">

##### Example container configuration for detached migration process – AWS ECS

For AWS ECS you can use the `dependsOn` setting to ensure the correct container start order:

```
ckeditor_cs_container_definition = {
    name              = "ckeditor_cs"
    image             = local.docker_image
    essential         = true
    environment       = local.environment_variables
    dependsOn = [
      {
        containerName = "${local.service_name}-migrator",
        condition     = "SUCCESS"
      }
    ]
    // The rest of container definition
  }
  ckeditor_cs_migrator_container_definition = {
    name         = "${local.ckeditor_cs_container_definition.name}-migrator"
    image        = local.ckeditor_cs_container_definition.image
    essential    = false
    healthCheck  = null
    environment  = concat(
      local.ckeditor_cs_container_definition.environment,
      [
        {
          name  = "MIGRATE_ONLY",
          value = "true"
        }
      ]
    )
    // The rest of container definition
  }

```

Make sure `ckeditor_cs_migrator_container_definition` has the `healthCheck` parameter set to `null`. A container in the `MIGRATE_ONLY` mode does not expose any HTTP endpoint and for larger databases, the run time may be long.

<a id="cs/latest/onpremises/docx-onpremises/api.html">source file: "cs/latest/onpremises/docx-onpremises/api.html"</a>

## Import and Export to Word On-Premises REST API usage

Import and Export to Word On-Premises consisits of two services:

* Export to Word provides convertion from an HTML document to a `.docx` file via Restful API.
* Import from Word allows importing `.docx` file and converting it into a styled HTML document with comments and suggestions attached.

The API is available on `http://localhost:[port]` (by default the `port` is `8080`).

If you have the authorization for the API enabled, you should provide an authorization token. More instructions you can find in the [authorization](#cs/latest/onpremises/docx-onpremises/authorization.html) section.

<a id="cs/latest/onpremises/docx-onpremises/authorization.html">source file: "cs/latest/onpremises/docx-onpremises/authorization.html"</a>

## Import and Export to Word On-Premises authorization

To enable authorization, set up the `SECRET_KEY` environment variable during the [installation](#cs/latest/onpremises/docx-onpremises/installation.html).

If the `SECRET_KEY` variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the `Authorization` header for each request sent to the [Import and Export to Word REST API](#cs/latest/onpremises/docx-onpremises/api.html).

<a id="cs/latest/onpremises/docx-onpremises/authorization.html--generating-the-token">

### Generating the token

We highly recommend using the libraries listed on [jwt.io](http://jwt.io/) to generate the token. The token is considered valid, when:

* it is signed with the same `SECRET_KEY` as passed to the Import and Export to Word On-Premises instance,
* it was created within the last 24 hours,
* it is not issued in the future (e.i. the `iat` timestamp cannot be newer than the current time),
* it has not expired yet.

The tokens for the Import and Export to Word On-Premises do not require any additional claims, such as the environment ID (which is specific for Collaboration Server On-Premises), so you can create the token with an empty payload.

If your use case involves sending requests from your backend server, then you can generate JWT tokens locally, as it is done in our [request example](#cs/latest/onpremises/docx-onpremises/authorization.html--request-example-with-an-authorization-header).

In the case of editor plugins or other frontend usages, you should create a token endpoint, that returns a valid JWT token for authorized users. Here you can find an example of an [token endpoint implementation](#cs/latest/examples/token-endpoints/nodejs.html--export-to-pdf-and-import-and-export-to-word-on-premises).

<a id="cs/latest/onpremises/docx-onpremises/authorization.html--using-editor-plugins">

### Using editor plugins

The are are two plugins available for CKEditor 5: [Export to Word](#ckeditor5/latest/features/converters/export-word.html) and [Import from Word](#ckeditor5/latest/features/converters/import-word/import-word.html). The plugins will automatically request the token from the given `tokenUrl` variable and will set the `Authorization` header when making an export request. Refer to the respective guides for details on adding the Export to Word and Import from Word features to your WYSIWYG editor!

<a id="cs/latest/onpremises/docx-onpremises/authorization.html--request-example-with-an-authorization-header">

### Request example with an Authorization header

The following example presents a request that generates a valid JWT token and sets it as an `Authorization` header:

```
const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const SECRET_KEY = 'secret';

const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );

const data = {
   html: "<p>I am a teapot</p>",
   css: "p { color: red; }",
};

const config = {
   headers: {
      Authorization: token
   },
   responseType: 'arraybuffer',
};

axios.post( 'http://localhost:8080/v1/convert', data, config )
   .then( response => {
      fs.writeFileSync('./file.docx', response.data, 'binary');
   } ).catch( error => {
      console.log( error );
   } );

```

`SECRET_KEY` – this is the key what has been passed to the Import and Export to Word On-Premises instance.

Please refer to the [Import and Export to Word REST API documentation](https://docx-converter.cke-cs.com/docs) to start using the service.

Note: If you use API clients like Postman or Insomnia, then set the JWT token as an `Authorization` header in the `Headers` tab. Do not use the built-in token authorization as this will generate invalid header with a `Bearer` prefix added to the token.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html">source file: "cs/latest/onpremises/docx-onpremises/changelog.html"</a>

## Import and Export to Word On-Premises

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1233-2026-04-15">

### 1.23.3 (2026-04-15)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1232-2026-03-26">

### 1.23.2 (2026-03-26)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes">

#### Bug fixes

* Fixed support for conversion when no secret key is provided  
In the recent release, the possibility of using the converter without a secret key was blocked. This release restores the possibility of using the converter without a secret key set. So now the converter can be configured to be used without the Authorization header back.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-2">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1231-2026-03-10">

### 1.23.1 (2026-03-10)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-3">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-2">

##### Bug fixes

* Fixed missing error details in HTML conversion error responses.  
When submitting an invalid DOCX file for HTML conversion, the error response now correctly includes the errors array in the response data, matching the behavior of DOCX conversion errors.
* Ignore trailing whitespace.  
In Word, some whitespace characters, including the space character, when placed at the end of a line or a paragraph, do not participate in document layout. However, the converter used to preserve them and only removed certain formatting properties (e.g., background color) from them, leading to issues with horizontal text alignment or table cell width. Now, the converter ignores such characters.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-3">

##### Bug fixes

* Fixed conversion hanging indefinitely when fetching unavailable images.  
The converter now handles network requests through a single HTTP client, preventing situations where unreachable images could cause the conversion to hang or produce squished images.
* Fixed validation of merge fields data.  
Non-array merge field data is now properly rejected upfront, preventing potential serialization issues during conversion.
* Correctly convert line height.  
Export to Word had several bugs in calculations of line height, which led to incorrect line spacing in Word and caused unintentional visual changes in documents that are exported and then imported again. These problems were addressed in this release, and line height converts properly now.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1230-2025-01-15">

### 1.23.0 (2025-01-15)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-2">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features">

##### Features

* Added support for conversion of footnotes and endnotes (supported in CKEditor 5 v47.4.0 and up).  
The converter is now capable of converting footnotes and endnotes from Word to CKEditor 5\. Since the editor only supports endnotes, the converter transforms footnotes into endnotes.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-2">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-2">

##### Features

* Added support for conversion of HTML footnotes (supported in CKEditor 5 v47.4.0 and up).  
Export for Word now supports converting footnotes from CKEditor 5 to endnotes in Word.
* Added support for non-https resource requests  
The converter now allows to request resources over http.  
To enable this feature, the `ALLOW_INSECURE_RESOURCES` environment variable must be set to `true`.  
It is disabled by default for security reasons.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-4">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1223-2025-11-19">

### 1.22.3 (2025-11-19)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-5">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1222-2025-09-23">

### 1.22.2 (2025-09-23)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-6">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1221-2025-07-28">

### 1.22.1 (2025-07-28)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-3">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-4">

##### Bug fixes

* Fixed an issue with the incorrect application of CSS in Export to Word conversion  
If camelCase was used in a CSS class ( `.someClass` ), styles were incorrectly applied during Export to Word. The issue has been resolved, and CSS styles are now applied correctly, respecting class name casing.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-7">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1220-2025-06-03">

### 1.22.0 (2025-06-03)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-3">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-3">

##### Features

* Added support for headers and footers.  
They support the same formatting as the main document content. The converter also supports different types of headers and footers:

  * first page ones,
  * even page ones,
  * odd page ones,
  * and default ones (if the header/footer is the same for all pages).  
Page number and total pages fields are also supported. They are outputted as `<span class="pageNumber"></span>` and `<span class="totalPages"></span>`. Thanks to that, imported page numbering is compatible with the one supported by the Export to Word.  
Please note that only headers and footers from the first section in the document are converted.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-5">

##### Bug fixes

* Fixed an issue with parsing horizontal lines breaking conversion  
If a horizontal line was followed immediately by a page break without any newline between them, the converter errored. After the fix, such cases are correctly converted. The fix additionally improved support for suggestions added to the horizontal line – especially when it’s followed by a page break. Without the fix, a suggested horizontal line was missing from the document.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-4">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-4">

##### Features

* Added support for Newline suggestions  
Newline suggestions between paragraphs and list items are now supported. Additionally, comments added to such suggestions are also supported.  
Alongside the support for newline suggestions, the overall support for suggestions has been improved. The enhancements include support for suggestions on `<br>` elements and suggestions in image captions.
* Added Horizontal padding support  
Prior to this change, only `margin-left` and `margin-right` CSS properties were translated to horizontal margins in Word. This feature also introduced support for indentation applied by `padding-left` and `padding-right` CSS properties. Now, the indentation is the sum of margins and padding, e.g. if the element has `margin-left` of 10px and `padding-left` of 20px, its left margin in Word will be 30px.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-8">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1210-2025-04-08">

### 1.21.0 (2025-04-08)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-4">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-5">

##### Features

* Added generic font families to fonts imported from MS Word  
MS Word can include many fonts that are not available in the browser, but are part of the user’s OS.  
To make sure that fonts rendered by the browser resemble what the user sees in Word, we have introduced generic  
font families in outputted font stacks. For example, instead of setting font-family to `Calibri`, the converter  
now sets it to `Calibri, sans-serif`.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-6">

##### Bug fixes

* Fixed an issue with incorrectly recognized multi-level lists  
When a multi-level list definition included other list item types that were not used in the list itself,  
the converter produced a normal list. This optimization makes sure that multi-level lists with unused other  
list type definitions are still treated as multi-level.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-5">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-6">

##### Features

* Added table of contents support  
Export for Word now supports the table of contents feature that is converted into a proper MS Word feature.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-7">

##### Bug fixes

* Fixed missing support for Windows/DOS line endings  
Added support for Windows/DOS line endings, i.e. `\r\n`.
* Fixed failing conversion when converting unsupported drawings  
In rare cases when an unsupported type of drawing was added to the document as a suggestion, the import suggestion failed.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-9">

#### Common changes

* Improved memory consumption  
The converter now consumes less memory while processing large documents.
* Updated node version to 22.14.0  
The node version has been updated to 22.14.0 improving the security, reliability  
and performance of the application.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1201-2025-02-11">

### 1.20.1 (2025-02-11)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-5">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-8">

##### Bug fixes

* Fixed incorrect indentation in paragraphs with disabled numbering  
When a paragraph inherited a numbering definition containing paragraph indentation from a style definition, but had that numbering explicitly disabled in direct formatting, the indentation was still being applied. In this release, this bug was fixed, and such paragraphs no longer include the indentation inherited from a numbering definition.
* Fixed an exception thrown in documents containing references to non-existent abstract numbering definitions

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-10">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1200-2024-12-17">

### 1.20.0 (2024-12-17)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-6">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-7">

##### Features

* Added multi-level lists  
With this release, we introduced support for legal style numbering. That kind of multi-level list refers to a numbering format used primarily in legal documents, characterized by a hierarchical structure where each section, subsection, and clause is distinctly numbered (e.g., 1, 1.1, 1.1.1) to facilitate clear referencing and organization. This feature is fully integrated with [CKEditor 5 Multi-level lists](#ckeditor5/latest/features/lists/multi-level-lists.html).
* Added document lists  
Paragraphs that follow list items with equal or greater indentation are now automatically included as part of the list item, preserving complex list structures from Word documents.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-9">

##### Bug fixes

* Fixed an issue with incorrectly numbered list items  
Fixed Word list import to properly handle custom number overrides, ensuring that lists with manually adjusted numbering sequences are accurately preserved in the resulting HTML output.
* Fixed HTML encoding for selected attributes  
Some attributes could generate invalid HTML if not properly encoded. This bugfix ensures that the produced HTML is fully HTML 5 compliant.
* Updated URL protocol validation  
Updated protocol handling to omit specific non-web protocols that could produce non-compliant HTML.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes">

##### Other changes

* Improved file validation in Import from Word  
In case of incompatible file import a proper error message will be returned.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-6">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-8">

##### Features

* Added multi-level lists  
With this release, we introduced support for legal style numbering. That kind of multi-level list refers to a numbering format used primarily in legal documents, characterized by a hierarchical structure where each section, subsection, and clause is distinctly numbered (e.g., 1, 1.1, 1.1.1) to facilitate clear referencing and organization. This feature is fully integrated with [CKEditor 5 Multi-level lists](#ckeditor5/latest/features/lists/multi-level-lists.html).
* Added document lists  
List items containing block elements are now automatically flattened when exporting to Word, with nested content converted into properly indented paragraphs following their respective list items.
* Improved image spacing  
Export to Word is now capable of recognizing image margins for float elements (CSS `float` property), maintaining proper spacing between floating images and surrounding text.
* Added support for image merge fields  
Added support for the merge fields within image source attributes, allowing dynamic image references when field values are provided. Note: due to Word limitations, this cannot generate new image fields in the document on its own, you have to provide merge field value via the `merge_fields.data` configuration option.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-11">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1190-2024-10-01">

### 1.19.0 (2024-10-01)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-form-word">

#### Import form Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-9">

##### Features

* Added support for detecting text content language  
The text content language is now preserved by the converter and output as the appropriate lang attribute.  
This feature is fully compatible with CKEditor 5’s Text part language feature.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-10">

##### Bug fixes

* Fixed incorrectly converted track changes newline insertions in lists  
When the last item in a nested list included a newline insertion, it was incorrectly converted and became  
attached to the parent list. This issue has been resolved.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-7">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-10">

##### Features

* Added watermark support  
You can now add a semi-transparent image watermark to each page of an exported Word document, ideal for branding, copyright protection, or decorative purposes. This feature is particularly useful for professional documents such as reports, contracts, or marketing materials. For more details, see the API watermark configuration option.
* Added bookmarks support  
The converter now transforms elements with the id attribute into Word document bookmarks, enabling quick navigation within the document.
* Added support for detecting text content language  
Text content language is now retained in exported Word documents, compatible with CKEditor 5’s Text part language feature.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-11">

##### Bug fixes

* Fixed table rendering across multiple pages  
Fixed an issue where tables spanning multiple pages had incorrect break points if the CSS did not specify a parent element font size.  
Table height is now calculated only when explicitly defined in CSS, allowing Word’s rendering engine to handle table pagination more accurately.
* Fixed issue with empty documents not preserving document language  
Empty documents now retain the specified content language in the exported Word document, ensuring a better editing  
experience even when no initial content is present.
* Fixed issue with images and links pointing to the same resource  
Documents containing the same src attribute for images and href for links are now correctly generated without breaking  
the document structure.
* Fixed attribute suggestions breaking the conversion ( EtW v1 version )  
The unsupported attribute suggestions are removed from the document.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-2">

##### Other changes

* Improved spacing between adjacent tables and block quotes  
When HTML contains two adjacent tables or block quotes, we insert a paragraph in-between to prevent Word from merging these elements.  
These paragraphs now use the “No Spacing” style, reducing formatting discrepancies.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-12">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1180-2024-08-06">

### 1.18.0 (2024-08-06)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-form-word-2">

#### Import form Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-11">

##### Features

* Added merge fields support  
Alongside the CKEditor 5 merge fields release, we have introduced merge fields for import from Word. Merge fields found in Word documents are preserved and outputted, with an option to define merge field prefixes and suffixes.  
You can find more information in the REST API documentation available under /v2/convert/docs#section/Import-from-Word/Configuration.
* Added the `timezone` option to help convert dates of the collaboration features more accurately  
To properly offset the date and time, the timezone option is used to inform the converter about the time zone in which the document was created. This option is required for the collaboration features to accurately calculate the `created_at` date.  
You can find more information in the REST API documentation available under /v2/convert/docs#section/Import-from-Word/Configuration.
* Collaboration features (comments and suggestions) will return the creation date.  
Both comments and suggestions have been improved to include the annotation creation date as the `created_at` property.  
Dates are ISO 8601 compatible.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-12">

##### Bug fixes

* Improved table border resolution  
In some cases, imported table borders were incorrectly applied or missing.
* Changed the `japaneseDigitalTenThousand` (Japanese Digital Ten Thousand Counting System) list style type to CSS `cjk-decimal`.  
Originally, that style was converted to `japanese-informal`, which did not properly match this list style type.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-8">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-12">

##### Features

* Added complete support for table borders formatting  
Now a change of table border color, style, and width, as well as creating tables with hidden borders to layout the content are supported.
* Added merge fields support  
Alongside the CKEditor 5 merge fields release, we have introduced merge fields for export to Word. Exported merge fields integrate well with the Word mail merge feature. You can also replace merge fields on the fly by providing merge field data in JSON format.  
You can find more information in the REST API documentation available under /v2/convert/docs#section/Export-to-Word/Configuration.
* Added support for document content language  
The document content language can be changed now by configuring the `document.language` option.  
This accepts a valid `BCP 47` language tag.  
You can find more information in the REST API documentation available under /v2/convert/docs#section/Export-to-Word/Configuration.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-13">

##### Bug fixes

* Fixed an issue with images positioned incorrectly with text wrap  
Images with wrap text or side image alignment in the document list were positioned incorrectly. After the fix, image positioning for these types of images is more precise.
* Fixed image caption positioning.  
A recent update in MS Word caused an issue where image captions would occupy the entire height of the image. This problem has now been addressed. After the fix, image captions are correctly positioned at the bottom of the image.
* Fixed incorrect background color inheriting.  
The background color defined for the `body` element could, in some cases, incorrectly impact the table header background color. This issue has been patched.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-3">

##### Other changes

* Improved the performance and memory consumption of the converter, making it even faster

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-13">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1170-2024-06-19">

### 1.17.0 (2024-06-19)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-7">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-13">

##### Features

* Added support for captioned images  
Captioned images exported by Export to Word 2.0 are now recognized in Import from Word and are properly converted to `<figure>` elements containing the caption in `<figcaption>`.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-14">

##### Bug fixes

* Fixed support for the “at least” line spacing option  
When a paragraph in Word had line spacing set to some minimum value using the “at least” option, that spacing made the imported content unreadable.  
CSS lacks a dedicated property for minimum line height; however, Import from Word converts such formatting to the `max()` CSS function, imitating the same feature from Word.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-9">

#### Export to Word

**Note:**

The `/v2/convert/html-docx` endpoint has been introduced with this version.  
The `v2` provides a number of improvements, optimizations and fixes to the Export to Word feature. All changes mentioned in the changelog applies to the `v2` version.  
In case of any problem or regression we encourage you to use the previous version and report the discovered problems through the support channel.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-14">

##### Features

* Added Auto-detection to some built-in Word styles  
Word has many predefined styles that can be explored using the Styles gallery. Export to Word can now automatically pick up some of them from the provided CSS style sheet and convert them to their respective style from Word. The following styles are currently supported:

  * Normal
  * Heading 1 through Heading 6
  * Plain Text
  * Quote
  * Code
  * Hyperlink
  * Table Grid
* Added table header rows support  
Table rows inside the first `<thead>` are converted to header rows in generated Word documents. Header rows repeat at the top of each document page in Word.
* Added table row height support  
Table rows have their height preserved now, maintaining the original table layout.
* Added support for table cell paddings  
Table cell padding is supported and properly converted to table cell margins in this version of Export to Word.
* Added support for more text-related CSS properties  
Various CSS properties related to text convert more properly now. This includes properties such as `font-weight`, `font-style`, `text-decoration`, named font-size CSS properties (`small`, `medium`, `large`, etc.), and many more.
* Added support for generic font families  
CSS allows specifying generic font families, such as `sans-serif` or `monospace`, in the `font-family` property. Previously, they were treated as font names, but in this version, they are now properly recognized and transformed into some well-known font families, for example Times New Roman.
* Added support of line spacing in paragraphs  
The `line-height` CSS property is now converted to line spacing formatting in Word, ensuring that paragraph spacing better matches the original document.
* Added support for spacing before and after paragraphs  
The converter supports `margin-top` and `margin-bottom` CSS properties now and converts them to respective paragraph spacing.
* Added support `list-style-type` defined in the CSS style sheet  
The previous converter version supported the `list-style-type` property only if it was defined directly on the element via the `style` attribute. Now, `list-style-type` defined in the provided CSS style sheet is also recognized and supported.
* Added support the `font-family` property in list items  
`font-family` can be applied directly to `<li>` elements and will be preserved in generated Word documents.
* Added support for `break-before` and `break-after` CSS properties  
HTML with these properties will generate a page break accordingly, enabling more control over page layout.
* Added support comments in more positions  
In the release, comments attached to various elements are supported. This includes, among others, comments attached to tables, table cells, horizontal lines and block images.
* Added time zone support in comment creation dates  
Creation dates of comments take their time zone into account now, allowing Word to correctly display them in the user’s local time zone.
* Added support for floating images  
This version of Export to Word supports images with the `float` CSS property.
* Added Base64 image support in headers and footers  
Previously, when a header or footer contained an image with its source encoded in Base64, the converter did not preserve the image. Now, it correctly converts such images.
* Added support for decorative images  
Images without or with an empty `alt` attribute are now marked as decorative images.
* Added support for image caption background color  
The image caption now supports background color with an alpha channel.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-15">

##### Bug fixes

* Fixed paragraph background color not applying to the entire paragraph.  
Before, the paragraph background color was applied only to the paragraph contents. Now, it’s added to the entire paragraph.
* Fixed handling `<span>` elements with custom CSS classes  
In the previous version, HTML documents containing `<span>` elements with custom class names didn’t convert properly. This issue has been resolved, and such documents are now generated correctly.
* Fixed rendering of text with inherited font size  
Previously, applying `font-size: inherit` to some text resulted in generating invisible text in the Word document. This was changed to display the text properly.
* Fixed handling of invalid Unicode characters  
Some Unicode characters are disallowed in Word documents and cannot be stored in them. The converter didn’t check their presence, which resulted in broken documents being generated. In this version, such characters are transformed into the `�` replacement character.
* Fixed broken list editing in generated documents  
Previously, when a generated document contained list items, their editing experience was broken when trying to indent them. That issue was resolved in this version.
* Fixed support for empty table cells  
When a table contained a cell without any content, or with empty elements (such as empty `<span>` elements), the generated documents were broken. In this converter version, such tables are converted properly.
* Fixed conversion of alternative image text  
In the previous version, images with the `alt` attribute were losing their alternative text during the conversion. That issue was addressed, and alternative text is now preserved.
* Fixed hyperlinks with captioned images  
Previously, when a hyperlink contained an image with a caption, the conversion resulted in a broken document. Now, the generated documents are valid.
* Fixed support for suggestions in list items  
In some cases, when a list item contained a text suggestion, it was possible for that suggestion to convert incorrectly, resulting in paragraphs and list items following the list item with the suggestion to be included in it. This release addresses this problem, and text suggestions in list items no longer include more content than they did in the source HTML.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-4">

##### Other changes

* Significantly improved conversion times  
With this release, we notably sped up the Export to Word converter, making it more suitable for converting large HTML documents.
* Extended support for image formats  
This version of the converter adds support for the following image formats:

  * `image/apng`
  * `image/avif`
  * `image/bmp`
  * `image/heic`
  * `image/tiff`
  * `image/webp`
* Improved image size support in all cases  
Unless specified otherwise in the CSS style sheet, image size is no longer restricted to the document size. Additionally, when the converter cannot fetch an image, it will retain the size of the placeholder that is displayed in browsers instead of changing it to a fixed value.
* Improved table background color conversion  
The previous version of the converter did not always convert background colors in tables properly. In this version, detection of background color in tables has been changed to more closely match the HTML standard, so table cells in generated documents no longer lose their background colors in some cases.
* Improved proper column width detection  
This version of Export to Word correctly recognizes table columns created via `<colgroup>` and `<col>` and their styling, such as the `width` CSS property.
* Improved table cell merging  
Previously, merged table cells did not work correctly in all configurations. This has been improved to handle more complex table layouts correctly.
* Improved conversion of percentages and relative units  
Percentages and units such as `em` or `rem` are now more accurately calculated to more closely match how browsers render them.
* Improved positioning of images  
The converter more accurately converts image positioning now, including image captions.
* Improved conversion of whitespace characters  
Whitespace characters in HTML have complex rules determining whether such characters should be rendered. Previously, they were lost in some situations during the conversion. This release addresses this long-standing issue, and whitespace characters are now preserved correctly.
* Improved support for nested comment threads and suggestions  
When a deletion suggestion starts at the same place as a comment thread, the suggestion is now correctly preserved.
* Improved the horizontal line support  
Horizontal lines are now rendered as actual lines rather than very narrow boxes, ensuring they appear correctly in generated documents.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-14">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1163-2024-04-30">

### 1.16.3 (2024-04-30)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-15">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1162-2024-03-05">

### 1.16.2 (2024-03-05)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-16">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1161-2024-01-09">

### 1.16.1 (2024-01-09)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-8">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-5">

##### Other changes

* Added the `text-decoration-skip-ink` CSS property to CSS resets
* Added the `font-size` CSS property of HTML headings to CSS resets

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-10">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-16">

##### Bug fixes

* Fixed suggestions attribute breaking a conversion  
The unsupported suggestions attributes are removed from the document.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-17">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.  
The above update patches the security vulnerability related to the heap buffer overflow risk.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1160-2023-11-14">

### 1.16.0 (2023-11-14)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-9">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-15">

##### Features

* Added support for newline suggestions  
This release adds support for newline suggestions. This type of suggestion occurs in Word documents when a hard line break is inserted or deleted while changes are being tracked.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-17">

##### Bug fixes

* Fixed support for checkboxes in tables  
Previously, when a table contained a checkbox inside a row or a cell, the converter didn’t recognize such a structure, and threw an error when performing some table operations. For example, when the cell containing the checkbox spanned several columns, the merging operation in the converter caused errors.
* Fixed inheritance of complex formatting properties  
Complex formatting properties, such as list numbering or underlines, weren’t always resolved correctly when they were defined on various levels of the style hierarchy. For example, paragraph styles that inherited a list definition from another paragraph style, but had a different list level specified, didn’t apply properly. This release adjusts resolving of such formatting.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-11">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-16">

##### Features

* Added support for custom headers while fetching external images  
Custom headers can now be added to every request which fetches external images.  
It can be used e.g. to authorize access to external images.  
The feature is available thanks to the `extra_http_headers` option.  
You will find more information in our documentation.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-18">

##### Bug fixes

* Fixed incorrect rendering of images if fetching any of the images failed.  
An image that couldn’t be loaded during the conversion is properly displayed as non-available in a Word document.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-18">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1151-2023-10-05">

### 1.15.1 (2023-10-05)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-19">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.  
The above update patches the security vulnerability related to the heap buffer overflow risk.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1150-2023-09-19">

### 1.15.0 (2023-09-19)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-10">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-17">

##### Features

* Added CSS resets and extended formatting support  
Browsers provide their own CSS stylesheets that apply default formatting to common HTML elements. Unfortunately, this formatting is incompatible with the default Word formatting. Previously, the IFW converter did not support overwriting conflicting browser styles. Now a new configuration option `formatting.resets` is available. It can be used to change selected formatting properties to the same values that are used in Word by default.  
Along with this change, we introduced the new `formatting` configuration option that can be used to control the outputted formatting in a more granular way:  
```  
type ConversionConfig = {  
    formatting?: {  
        resets?: 'none' | 'inline';  
        defaults?: 'none' | 'inline';  
        styles?: 'none' | 'inline';  
        comments?: 'none' | 'basic' | 'full';  
    };  
};  
```  
The old `default_styles` and `collaboration_features.comments_styles` options are now deprecated in favor of `formatting.defaults` and `formatting.comments` respectively.
* Added default table styles  
Tables in Word have some default formatting defined implicitly. For example, text in table cells is by default vertically aligned to the top, and tables themselves are aligned to the left. These properties differ from the default HTML formatting, where, for example, the content of table cells is by default centered. However, they are not saved anywhere in documents, so the converter added them as direct formatting to minimize the visual differences between Word and the HTML output. Unfortunately, this means that such default styles were always outputted regardless of whether the conversion of default formatting was actually enabled.  
In this release, the implicit table formatting starts being recognized as the default formatting and is no longer added to the output if the `formatting.defaults` option is set to `false`. Along with this change, we also extended support for default table formatting, and table borders are now collapsed by default.  
Please note that this may change the content produced by the converter when documents are converted with the conversion of default formatting disabled (which is the default case).

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-19">

##### Bug fixes

* Fixed support for simple fields  
Previously, some fields such as `DATE` could be incorrectly converted, resulting in content loss. Now, the converter will properly preserve the content of such fields.
* Fixed escaping font names in CSS  
When some part of a document was using a font with specific characters in its name, the converter outputted invalid CSS due to a lack of proper character escaping. This means that browsers ignored the outputted formatting and such fonts were not properly applied in the output. The Import from Word converter now properly escapes these characters.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-12">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-20">

##### Bug fixes

* Fixed support for images inside span elements within tables
* Fixed the rendering of documents with over 20,000 paragraphs
* Fixed a problem with preserving multiple successive spaces in exported documents  
Added a proper whitespace handling mechanism that preserves whitespace characters consistent with browser vendors.
* Fixed incorrect handling of suggestions in lists when a suggestion was nested inside an inline element with no other content  
The documents containing suggestions inside inline elements should no longer be broken.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-20">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1141-2023-07-25">

### 1.14.1 (2023-07-25)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-21">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1140-2023-07-11">

### 1.14.0 (2023-07-11)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-11">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-18">

##### Features

* Added support for the Strict Open XML format  
The `.docx` files can be saved in the Strict Open XML mode, which differs significantly from the regular mode. This release adds support for DOCX files saved in the strict mode, resulting in better coverage of supported document formats.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-21">

##### Bug fixes

* Advanced Table Formatting: Last column formatting is not applied to merged table cells  
Formatting of the last table column was ignored when the last table cell in a table row spanned multiple columns. Thanks to the fix, cells in the last column always have conditional formatting properly applied now.
* Advanced Table Formatting: Formatting of corner cells in the last column is not applied to merged table cells  
Formatting of corner cells in the last column was not applied when those cells spanned multiple columns. The fix should now ensure proper resolution of formatting for corner cells in the last column.
* Advanced Table Formatting: Similar formatting regions should be mutually exclusive  
When table cells belong to similar table regions, only formatting from one such region should be applied. For example, consider a table that contains a single cell. This cell belongs to both the first and the last column. However, in Word, only the formatting of the first column is applied to that cell. Import from Word follows the same behavior as Word now.
* Table of Contents: Line breaks in headings are not properly supported  
Headings in Word may contain soft line breaks, which are typically replaced by a single space character by default. However, the converter ignored those line breaks, resulting in a lack of whitespace in the output.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-22">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1130-2023-05-30">

### 1.13.0 (2023-05-30)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-13">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-19">

##### Features

* Added support for resolved comments  
Comments that are marked as `comment.is_resolved` will be resolved in a Word document.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-22">

##### Bug fixes

* Fixed generating Word documents with list suggestions  
Suggestions in list items sometimes caused producing broken Word documents
* Fixed broken conversion due to loading CSS  
Some CSS syntax caused conversion to fail. The fix skips the invalid CSS properties.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-12">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-20">

##### Features

* Added support for advanced table formatting  
In Word, table styles can define the formatting of particular table sections, for example, the background color of cells in the last table row. In fact, many table styles built-in into Word use such formatting. Now, the Import from Word converter recognizes and properly converts it.
* Added support for archived comments  
Recently, CKEditor 5 released a feature called “comments archive” that allows archiving comments that are no longer necessary. Word, on the other hand, has an option that marks comments and entire comment threads as resolved. Until now, the Import from Word converter did not return any information on whether a comment is resolved or not, but since this release converted comments contain a new property called is\_resolved that can be used to archive imported comments in CKEditor.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-23">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1120-2023-04-28">

### 1.12.0 (2023-04-28)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-13">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-21">

##### Features

* Added support for table of contents  
This release brings support for the table of contents. Currently, two possible formats of the table of contents are supported:

  1. Automatic table of contents
  2. Custom table of contents
* Added support for horizontal alignment of non-inline images  
In Word, there are two types of images: inline and floating. The latter can be freely positioned and have its other settings, such as text wrapping, modified. In this release, support for the horizontal alignment of floating images was added.  
Note that HTML does not support a centered image with text wrapped around it, and thus importing such images does not preserve text wrapping.
* Added support for 3D rotation via camera presets  
Extending support for image rotation from the previous release: support for camera presets was added. Camera presets available from the 3-D Rotation tab of the Format Picture menu and containing rotation settings are converted properly now.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-23">

##### Bug fixes

* Fixed incorrectly aligned images  
Disabling the `config.default_styles` option sometimes caused imported images to be misaligned. This release patched this issue and now images should have proper alignment regardless of the `default_styles` option.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-24">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1110-2023-04-04">

### 1.11.0 (2023-04-04)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-14">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-22">

##### Features

* Added support for text indentation  
The `text-indent` CSS property on paragraphs is properly recognized and applied to the Word document. Text indentation support is limited to absolute units, like pixels.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-24">

##### Bug fixes

* Fixed an issue where an invalid HTML table structure resulted in producing broken Word documents  
Tables that are missing some part of the proper table structure, for example, empty table rows, are now properly handled by the converter.
* Fixed an issue where block elements inside list items were producing invalid HTML  
Block elements inside list items are converted to inline ones to preserve the correct list structure. Tables are extracted from lists as they are not supported in lists by Word.
* Fixed an issue with fetching images from external servers  
`png` and `jpg` images are now always downloaded and included in the \`.docx\`\` file.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-14">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-23">

##### Features

* Added support for conversion of SVGs  
The Import from Word converter can correctly convert images using the SVG format. It supports both embedded and linked images.
* Added advanced underline styling  
Previously, the converter always outputted underline as a solid black line. Now, it supports underlines that use different colors or shapes. However, not all shapes available in Word are supported by CSS, hence some are transformed into the closest matching equivalents.  
Advanced underline styling is represented using various `text-decoration-*` CSS properties. Additionally, please note that CKEditor 5 may need extra General HTML Support (GHS) plugin configuration to preserve it.
* Added support for image rotation  
Image rotation is now preserved by the converter. Both 2D and 3D rotations are supported. Currently, the default camera preset is supported.  
Rotation is outputted as a transform CSS property, and thus it behaves slightly differently from Word: rotated images may overlap text in preceding and following paragraphs. This feature also needs an additional GHS configuration in order to work in CKEditor 5.
* Added bookmarks support  
Bookmarks are document regions associated with some name. They can be used, for example, to create links to fragments of a document. They are now supported by the Import from Word converter that represents them using an empty `<a>` element with the bookmark name saved in id and name attributes. Links to bookmarks are represented by URI fragments.  
Note that, presently, CKEditor 5 does not support bookmarks.
* Added support for custom unordered list bullets  
Many Word documents contain custom bullets in unordered lists. The converter is used to transform them into the default circle bullet. Now, it preserves them in most common cases. However, non-standard symbol typefaces may sometimes produce unexpected results for now.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-25">

##### Bug fixes

* Trailing whitespace characters no longer preserve the background color  
Some whitespace characters (such as the regular space or the em space) do not have their background color rendered by Word when they are at the end of a text line. The converter now detects such characters when they are located either at the end of a paragraph or before a soft line break and strips background styling from them. Note that the converter cannot detect trailing whitespace characters at the end of arbitrary text lines as of now.
* Emoji sequences with attached comments are no longer broken into parts  
Previously, the converter split emoji sequences into individual parts when a comment was attached to them. For example, the 👩‍👩‍👦‍👦 emoji sequence with a comment attached to it would be split into 👩👩‍👦‍👦. It is correctly preserved now.
* Fixed invalid conversion of list definitions using none numbering format  
List items that use the none numbering format and that do not have any additional numbering text are no longer outputted with the default circle bullet, but rather have no marker at all.
* Fixed parsing of external images  
Images that were not embedded into a document itself used to cause conversion errors. Now, the converter correctly supports them.
* Fixed comments conversion in empty tables  
Until now, comments attached to empty tables were not preserved. This is no longer the case. However, note that there’s still an open issue regarding comments in empty tables in CKEditor 5.
* Preserved level definitions in multi-level lists  
Skipped list levels are no longer represented by lists with invisible markers, but rather by particular list items with invisible markers. This improves the editing experience of such lists in CKEditor because items inserted at previously skipped levels have their marker formats preserved now.
* Improved handling of spaces  
The Import from Word converter follows the space behavior in HTML more strictly now. It also no longer eagerly transforms regular spaces into non-breaking ones. This improves line-wrapping behavior because in some cases, the styled text could cause unnecessary line wraps.
* Improved HTML output for collaboration features  
The HTML produced for collaboration features has been optimized to reduce unnecessary styling duplications over content that has the same visual effect.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-25">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--1100-2023-02-07">

### 1.10.0 (2023-02-07)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-15">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-24">

##### Features

* Added better support for complex suggestions nesting  
Significantly improved support for nested suggestions of both the insertion and deletion types.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-26">

##### Bug fixes

* Fixed nested suggestions generating a broken document  
Nested suggestions of insertion and deletion types sometimes resulted in producing broken documents. After the fix, complex suggestions nesting is more stable.
* Fixed various conversion issues caused by nesting content inside div elements  
In some cases, nesting content inside div elements resulted in producing broken documents or applying incorrect style over nested inline content. After the changes, content nested in div elements is properly recognized.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-26">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--190-2022-11-29">

### 1.9.0 (2022-11-29)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--export-to-word-16">

#### Export to Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-25">

##### Features

* Added the `base_url` conversion option  
This option allows setting the base URL for resolving images’ and links’ relative URLs in the content, e.g. setting the `base_url` option to `https://ckeditor.com` will result in resolving the `/docs` link as the `https://ckeditor.com/docs` one.
* Added support for SVG images  
SVG images are now supported by the converter, both as base64 and URL links.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-27">

##### Bug fixes

* Fixed the issue where conversion of the style element inside other elements breaks conversion.  
After the fix, the style element can be placed inside other elements, e.g. a div and the CSS styles will be properly preserved.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--import-from-word-15">

#### Import from Word

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-26">

##### Features

* Added the `config.collaboration_features.comments_styles` configuration option  
It allows to choose one of the existing presets (none, basic, full), allowing to configure which comments’ styles should be converted.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-28">

##### Bug fixes

* Fixed the issue where in rare cases imported tables had incorrect width
* Fixed the issue where in rare cases text background turned black
* Fixed incorrect parsing of suggestions that is applied to a link spanning over multiple blocks
* Fixed emoji groups being split during the conversion

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-6">

##### Other changes

* Reduced HTML payload size and improved its quality  
It was done by merging side CSS properties to CSS property shorthands.  
As an example, properties such as `border-top`, `border-right`, `border-bottom`, and `border-left` will be reduced to a single `border` property.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--common-changes-27">

#### Common changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--181-2022-11-08">

### 1.8.1 (2022-11-08)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-29">

#### Bug fixes

* Fixed incorrect log messages while using an unlimited license  
While using an unlimited license, notifications with information about overusage were present in the application logs.  
Now the logs are present only after exceeding the limits in case of a limited license.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--180-2022-11-02">

### 1.8.0 (2022-11-02)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-27">

#### Features

* Added support for Import from Word  
Import from Word allows to convert a Word file into HTML code. Comments and suggestions will also be extracted.  
You will find more information about the feature in our on-line documentation.  
The feature requires a separate license. To start using it, please contact our sales or subscribe to our free 30-day trial.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-7">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--174-2022-10-18">

### 1.7.4 (2022-10-18)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-8">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--173-2022-09-06">

### 1.7.3 (2022-09-06)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-30">

#### Bug fixes

* Fixed incorrect handling of page breaks inside table cells  
Page breaks inside table cells were breaking document conversion. After the fix, page breaks are properly recognized in the produced Word documents.
* Fixed conversion fails if figcaption was placed under a figure with a class attribute that lacks image or table class name  
When figcaption was placed under a figure with a class attribute that lacks an image class name, the conversion failed. After the fix, the conversion is successful and the figcaption is placed in the Word document.
* Fixed conversion fails if a figcaption was placed inside a table figure element  
After the fix, table figcaption elements are ignored, no longer causing the conversion to fail.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-9">

#### Other changes

* Improved error messages  
Messages returned by document conversion provide better debugging experience to integrators if the conversion failed.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--172-2022-07-26">

### 1.7.2 (2022-07-26)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-10">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--171-2022-06-14">

### 1.7.1 (2022-06-14)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-11">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--170-2022-05-05">

### 1.7.0 (2022-05-05)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-28">

#### Features

* Added support for specifying width of table cells and columns  
The width of table cells can be specified by the width style and the `colgroup` element.
* Added support for ARM64v8 CPU architecture  
The Export to Word On-Premises Server can now be run on machines with the ARM64v8 CPU architecture.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-12">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--160-2022-03-22">

### 1.6.0 (2022-03-22)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-29">

#### Features

* Introduced auto paragraphing for orphan nodes  
Orphan text or inline nodes are automatically wrapped with paragraphs.
* Added support for comments inside table cells  
Table cells show commented cell content if added.
* Added support for suggestions inside table cells  
Table cells show cell content suggestions if added.
* Improved features compatibility for older (<365) MS Word versions  
Documents with images in base64 format and tables are now correctly supported when opening documents with older MS Word versions (<365).

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-31">

#### Bug fixes

* Fixed empty href in links breaking conversion
* Fixed broken documents caused by invalid markup for comments
* Fixed an issue where code snippets in table cells have an additional paragraph under a snippet
* Fixed an issue where blockquote elements including plain text content broke document conversion

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-13">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.
* Cleaned up dependencies
* Improved error messages  
Some of the errors now contain more detailed messages, including explanations and possible actions to solve the problem.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--152-2022-02-08">

### 1.5.2 (2022-02-08)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-14">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--151-2022-01-18">

### 1.5.1 (2022-01-18)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-15">

#### Other changes

* Update Node.js to version 16
* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--150-2021-11-16">

### 1.5.0 (2021-11-16)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-30">

#### Features

* Added support for autoparagraphing plain text comments  
Comment content property was only accepting HTML content. From now on, it is possible to use plain text also, which helps with custom CKEditor 5 comments integration.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-32">

#### Bug fixes

* Fixed incorrect generation of suggestions for new paragraphs

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-16">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.  
From this version on, the Docker Engine 20.10 or higher is recommended.
* Updated base docker image (Alpine Linux) from version 3.12 to 3.14
* Added an orientation parameter to the demo page

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--140-2021-10-05">

### 1.4.0 (2021-10-05)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-31">

#### Features

* Added support for custom numbering in lists  
List styles supported in CKEditor 5 are also supported by the converter.
* Enabled starting ordered lists from number other than 1  
Starting an order list from number other than 1 can be accomplished by providing a \[start\] attribute.
* Added support for list indentation  
You can control the indentation of list elements by providing margin style.
* Added support for table and table figure width  
You can control the width of table elements by providing width attribute or style.
* Added support for page orientation  
Page orientation can be set using the `options.orientation` property, accepting portrait (default) and landscape values.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-33">

#### Bug fixes

* Fixed documents broken due to inserting empty table cells or table cells with multiple spaces
* Fixed conversion of images that are not inside a paragraph or a figure element
* Fixed issue with suggestions spanning two paragraphs instead of ending on the first one
* Fixed incorrect generation of suggestions for new paragraphs

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-17">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--130-2021-08-24">

### 1.3.0 (2021-08-24)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-32">

#### Features

* Increased maximum size of the HTML  
The service allows to convert HTML with the maximum size of the content 20 MB.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-18">

#### Other changes

* Improved logs readability
* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--121-2021-04-04">

### 1.2.1 (2021-04-04)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-33">

#### Features

* Introduced support for inline images  
Inline images (images that are inside a paragraph) are now correctly rendered.
* Introduced support for nested tables  
The converter now supports HTML with nested tables (tables inserted into other tables’ cells).

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-34">

#### Bug fixes

* Fixed the header/footer CSS validation. CSS is now not obligatory
* Fixed adjacent `hr`s rendering
* Fixed the generation of documents containing `div` elements with `table` elements inside
* Fixed the API section in the documentation

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-19">

#### Other changes

* Cleaned up logs  
Removed stack traces, fixed data serialization and improved messages.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--110-2021-02-25">

### 1.1.0 (2021-02-25)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-34">

#### Features

* Added validation for document’s margins  
Supported units: `in`, `cm`, `mm`, `px`.
* Added support for auto pagination feature  
The auto pagination feature is enabled by default now.
* Added a creation date for comments  
The `created` param is required for comments now.
* Added the timezone option for a document  
Use the `timezone` option to set a document timezone. For example, if you use Comments and suggestions feature, created date time metadata will include the provided timezone option or UTC if the timezone option has not been set.
* Added support for tables alignment  
Enabled support to align tables to left and right using CSS `float` property.
* Added support for comments in suggestion threads  
Comments inside suggestion threads are preserved as a separate comment thread on the same range as suggestion.
* Added support for the page number and total pages in document headers and footers  
Headers and footers support dynamic data like current page number and total page number. It can be inserted by using the special placeholder element in header/footer HTML. For current page number use  and  for total page number.

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--bug-fixes-35">

#### Bug fixes

* Fixed block quotes nested inside a table breaks a document
* Fixed Horizontal line after or before a code block is rendered inside it
* Fixed the styled text inside a link causes a link loss

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--other-changes-20">

#### Other changes

* Improved various document formatting to make it more similar to CKEditor 5 content
* Improved demo page  
The demo page is now more readable and allows to use all available converter’s features.
* Updated documentation

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--100-2020-08-25">

### 1.0.0 (2020-08-25)

<a id="cs/latest/onpremises/docx-onpremises/changelog.html--features-35">

#### Features

* Added On-Premise version of DOCX Converter.  
The service allows to convert HTML into DOCX documents via the REST API.
* Added authorization.  
JWT authorization can be set with `SECRET_KEY` environment variable.

<a id="cs/latest/onpremises/docx-onpremises/index.html">source file: "cs/latest/onpremises/docx-onpremises/index.html"</a>

## Import from Word and Export to Word On-Premises

Import from Word and Export to Word is a set of two converter services that allow for both exporting structured HTML content (e.g. created with CKEditor 5 WYSIWYG editor) into a `.docx` Word file (the Export to Word converter) and for importing content from `.docx` and `.dotx` files and converting it into a styled HTML document with comments and suggestions attached (the Import from Word converter).

The On-Premises version of the Import and Export to Word feature is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the Export to Word and Import from Word converters available as SaaS.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/docx-onpremises/overview.html) – An introduction to Import and Export to Word On-Premises.
* [Requirements](#cs/latest/onpremises/docx-onpremises/requirements.html) – Learn about the prerequisites to install and run Import and Export to Word On-Premises.
* [Installation](#cs/latest/onpremises/docx-onpremises/installation.html) – Learn how to install Import and Export to Word On-Premises.
* [API](#cs/latest/onpremises/docx-onpremises/api.html) – Learn how to use the Import and Export to Word REST API.
* [Authorization](#cs/latest/onpremises/docx-onpremises/authorization.html) – Learn how to add authorization to Import and Export to Word On-Premises.
* [SSL communication](#cs/latest/onpremises/docx-onpremises/ssl.html) – Learn how to set up secure communication with Import and Export to Word On-Premises.
* [Logs](#cs/latest/onpremises/docx-onpremises/logs.html) – Learn how to manage the logs of Import and Export to Word On-Premises.

<a id="cs/latest/onpremises/docx-onpremises/installation.html">source file: "cs/latest/onpremises/docx-onpremises/installation.html"</a>

## Import and Export to Word On-Premises installation

<a id="cs/latest/onpremises/docx-onpremises/installation.html--supported-technologies">

### Supported technologies

The application is provided as a docker image by default.

It can be run with any Open Container runtime tool e.g. [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

Refer to the [Requirements guide](#cs/latest/onpremises/docx-onpremises/requirements.html) for more information about the hardware and software requirements to run the Import and Export to Word On-Premises.

<a id="cs/latest/onpremises/docx-onpremises/installation.html--setting-up-the-application-using-kubernetes-with-helm-charts">

### Setting up the application using Kubernetes with Helm charts

Use the provided Helm chart to set up the Import and Export to Word On-Premises.  
More instructions and the Helm chart you will find [in our repository](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/kubernetes/helm/ckeditor-docx-converter).

<a id="cs/latest/onpremises/docx-onpremises/installation.html--setting-up-the-application-using-a-docker-container">

### Setting up the application using a Docker container

1. Use instructions from the [Customer Portal](https://portal.ckeditor.com/) to log into the Export to Word On-Premises (DOCX converter) Docker registry and pull the Docker image.
2. Containerize the application using `docker` or `docker-compose`.
3. Use a demo page to verify if the application works properly.

<a id="cs/latest/onpremises/docx-onpremises/installation.html--containerize-example-using-docker">

#### Containerize example using `docker`

Launch the Docker container:

```
docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/docx-converter:[version]

```

If you want use authorization you should provide `SECRET_KEY`:

```
docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] -e SECRET_KEY=[your_secret_key] docker.cke-cs.com/docx-converter:[version]

```

You can read more about using authorization in the [authorization](#cs/latest/onpremises/docx-onpremises/authorization.html) section.

<a id="cs/latest/onpremises/docx-onpremises/installation.html--containerize-example-using-docker-compose">

#### Containerize example using `docker-compose`

1. Create the `docker-compose.yml` file:

```
version: "3.8"
  services:
    image: docker.cke-cs.com/docx-converter:[version]
      ports:
        - "8080:8080"
      restart: always
      init: true
      environment:
        LICENSE_KEY: your_license_key
        # Secret Key is optional
        SECRET_KEY: secret_key

```

For details on `SECRET_KEY` usage check the [authorization](#cs/latest/onpremises/docx-onpremises/authorization.html) section.

1. Run:

```
docker-compose up

```

<a id="cs/latest/onpremises/docx-onpremises/installation.html--notes">

### Notes

* Without a correct `LICENSE_KEY` the application will not start. If the license is invalid, you’ll get a `Wrong license key` error in the logs and the application will not run.
* You should override the `SECRET_KEY` variable using a unique and hard to guess string for security reasons.

<a id="cs/latest/onpremises/docx-onpremises/installation.html--next-steps">

### Next steps

Use the <http://localhost:8080/v1/convert> endpoint to export DOCX files. Check out the [authorization](#cs/latest/onpremises/docx-onpremises/authorization.html) section to learn more about tokens and token endpoints.

You can also use the demo page available on <http://localhost:8080/demo> to generate an example DOCX file.

Refer to the Export to Word REST API documentation on [http://localhost:8080/docs](http://localhost:8080/demo) for more details.

<a id="cs/latest/onpremises/docx-onpremises/logs.html">source file: "cs/latest/onpremises/docx-onpremises/logs.html"</a>

## Import and Export to Word On-Premises logs

The logs from Import and Export to Word On-Premises are written to `stdout` and `stderr`. Most of them are formatted in JSON. They can be used for monitoring or debugging purposes. In production environments, we recommend storing the logs to files or using a distributed logging system (like ELK or CloudWatch).

<a id="cs/latest/onpremises/docx-onpremises/logs.html--monitoring-import-and-export-to-word-with-logs">

### Monitoring Import and Export to Word with logs

To get more insight into how the Import and Export to Word On-Premises is performing, we built logs that can be used for monitoring. To enable these, just add the `ENABLE_METRIC_LOGS=true` environment variable.

<a id="cs/latest/onpremises/docx-onpremises/logs.html--log-structure">

#### Log structure

The log structure contains the following information:

* `handler` – A unified identifier of action. Use this field to identify calls.
* `traceId` – A unique RPC call ID.
* `tags` – A semicolon-separated list of tags. Use this field to filter metrics logs.
* `data` – An object containing additional information. It might vary between different transports.
* `data.duration` – The request duration in milliseconds.
* `data.transport` – The type of the request transport. It could be `http` or `ws` (websocket).
* `data.status` – The request status. It can be equal to `success`, `fail`, `warning`.
* `data.statusCode` – The response status in HTTP status code standard.

Additionally, for the HTTP transport, the following information is included:

* `data.url` – The URL path.
* `data.method` – The request method.

In case of an error, `data.status` will be equal to `failed` and `data.message` will contain the error message.

An example log for HTTP transport:

```
{
  "level": 30,
  "time": "2021-03-09T11:15:09.154Z",
  "msg": "Request summary",
  "handler": "postConvert",
  "traceId": "85f13d92-57df-4b3b-98bb-0ca41a5ae601",
  "data": {
    "duration": 752,
    "transport": "http",
    "statusCode": 200,
    "status": "success",
    "url": "/v1/convert",
    "method": "POST"
  },
  "tags": "metrics"
}

```

<a id="cs/latest/onpremises/docx-onpremises/logs.html--docker">

### Docker

The docker has built-in logging mechanisms that capture logs from the output of the containers. The default logging driver writes the logs to files.

When using this driver, you can use the `docker logs` command to show logs from a container. You can add the `-f` flag to view logs in real time. Refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/logs/) for more information about the `logs` command.

<a id="cs/latest/onpremises/docx-onpremises/logs.html--distributed-logging">

### Distributed logging

If you are running more than one instance of the Import and Export to Word On-Premises, we recommend using a distributed logging system. It allows you to view and analyze logs from all instances in one place.

<a id="cs/latest/onpremises/docx-onpremises/logs.html--aws-cloudwatch-and-other-cloud-solutions">

#### AWS CloudWatch and other cloud solutions

If you are running Import and Export to Word On-Premises in the cloud, the simplest and recommended way is to use a service which is available at the selected provider. Here are some of the available services:

* AWS – [CloudWatch](https://aws.amazon.com/CloudWatch)
* Google Cloud – [Cloud Logging](https://cloud.google.com/logging)
* Azure – [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/)

To use CloudWatch with AWS ECS, you have to create a log group before and change the log driver to `awslogs`. When the log driver is configured properly, logs will be streamed directly to CloudWatch.

The `logConfiguration` may look similar to this:

```
"logConfiguration": {
  "logDriver": "awslogs",
  "options": {
    "awslogs-region": "us-west-2",
    "awslogs-group": "cksource",
    "awslogs-stream-prefix": "ck-docx-converter-logs"
  }
}

```

Refer to the [Using the awslogs Log Driver](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using%5Fawslogs.html) article for more information.

<a id="cs/latest/onpremises/docx-onpremises/logs.html--on-premises-solutions">

#### On-Premises solutions

If you are using your own infrastructure or for some reason cannot use the service offered by your provider, you can always use some on-premises distributed logging system.

There are a lot of solutions available, including:

* [ELK](https://www.elastic.co/what-is/elk-stack) \+ [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html)  
This is a stack built on top of Elasticsearch, Logstash and Kibana. In this configuration, Elasticsearch stores logs, Filebeat reads logs from Docker and sends them to Elasticsearch, and Kibana is used to view them. Logstash is not necessary because logs are already structured.
* [Fluentd](https://www.fluentd.org/)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/fluentd) to send the logs. It has a built-in frontend, but can also be integrated with Elasticsearch and Kibana for a better filtering.
* [Graylog](https://www.graylog.org)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/gelf) to send the logs. It has a built-in frontend and needs Elasticsearch to store the logs as well as a MongoDB database to store the configuration.

<a id="cs/latest/onpremises/docx-onpremises/logs.html--example-configuration">

##### Example configuration

The example configuration uses Fluentd, Elasticsearch and Kibana to capture logs from Docker.

Before running Import and Export to Word On-Premises, you have to prepare the logging services. For the purposes of this example, Docker Compose is used. Create the `fluentd`, `elasticsearch` and `kibana` services inside the `docker-compose.yml` file:

```
version: '3.7'
services:
  fluentd:
    build: ./fluentd
    volumes:
      - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
    ports:
      - "24224:24224"
      - "24224:24224/udp"

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
    expose:
      - 9200
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:6.8.5
    environment:
      ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
    ports:
      - "5601:5601"

```

To integrate Fluentd with Elasticsearch, you first need to install `fluent-plugin-elasticsearch` in the Fluentd image. To do this, create a `fluentd/Dockerfile` with the following content:

```
FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
    && gem install fluent-plugin-elasticsearch \
    && gem sources --clear-all

```

Next, configure the input server and connection to Elasticsearch in the `fluentd/fluent.conf` file:

```
<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>
<match *.**>
  @type copy
  <store>
    @type elasticsearch
    host elasticsearch
    port 9200
    logstash_format true
    logstash_prefix fluentd
    logstash_dateformat %Y%m%d
    include_tag_key true
    type_name access_log
    tag_key @log_name
    flush_interval 1s
  </store>
  <store>
    @type stdout
  </store>
</match>

```

Now you are ready to run the services:

```
docker-compose up --build

```

When the services are ready, you can finally start the Import and Export to Word On-Premises.

```
docker run --init -p 8080:8080 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
docker.cke-cs.com/docx-converter:[version]

```

Now open Kibana in your browser. It is available at <http://localhost:5601/>. In the first run, you may be asked about creating an index. Use the `fluentd-*` pattern and press the “Create” button. After this step, your logs should appear in the “Discover” tab.

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html">source file: "cs/latest/onpremises/docx-onpremises/nightly-releases.html"</a>

## Nightly releases

This article describes the purpose and usage of nightly releases of Import and Export to Word On-Premises images.

Nightly images are released every day. During the automatic release, we run our tests to make sure that these images are working correctly, but unlike stable releases, nightly builds do not go through our full release process and are not tested and approved by our Quality Assurance.

Nightly images include all of the changes that are merged on our development branches. This allows you to access new features or receive fixes faster than with stable on-premises images.

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html--dangers-of-using-nightly-builds">

### Dangers of using nightly builds

Nightly builds are released automatically. By the nature of these images, they should be treated as unstable. Running an On-Premises application using these images may result in some unexpected behaviors, undocumented features or known and unknown defects.

You need to ensure that the versions that you are willing to run are working correctly and will not impact your application negatively. We highly recommend using DEV/UAT environments first and going through the process of quality acceptance on your side, before you use nightly images in production.

By using the nightly builds you accept the risks mentioned in the documentation.

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html--nightly-images-usage">

### Nightly images usage

There is a difference between the usage of nightly and stable releases of Import and Export to Word On-Premises. Instead of the `docx-converter` image, you should use the `docx-converter-nightly` images. Notice that the version of nightly images also includes a date and a hash. This date part can help you find the latest version of the nightly build. Example usage:

```
version: "2.2"
services:
    docx-converter-nightly:
        image: docker.cke-cs.com/docx-conveter-nightly:1.16.1-20240227-a846c6d954 # change the version
        ports:
        - "8080:8080"
        # environment variables and other configuration

```

Nightly builds are available only as docker images.

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html--list-of-available-nightly-versions">

### List of available nightly versions

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html--nightly-versions">

<a id="cs/latest/onpremises/docx-onpremises/nightly-releases.html--fetching-the-latest-nightly-version">

### Fetching the latest nightly version

If you want to automate the process of updating your application and automatically use the latest versions of nightly builds you can make a GET request at <https://docker.cke-cs.com/api/versions/docx-converter-nightly>. This will fetch the JSON with all available versions. Use the date in the version to find the latest image that can be used in your application.

<a id="cs/latest/onpremises/docx-onpremises/overview.html">source file: "cs/latest/onpremises/docx-onpremises/overview.html"</a>

## Import from Word and Export to Word On‑Premises – overview

Import and Export to Word is a set of two converter services that allow for both exporting a structured HTML content (e.g. created with CKEditor 5 WYSIWYG editor) into a `.docx` Word file (the Export to Word converter) and for importing content from `.docx` and `.dotx` files and converting it into a styled HTML document with comments and suggestions attached (the Import from Word converter).

About [Import from Word](#cs/latest/guides/import-from-word/overview.html) and [Export to Word](#cs/latest/guides/export-to-word/overview.html) features you can read in a dedicated sections of the documentation.

The On-Premises version of the Export to Word and Import from Word features is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the Export to Word and Import from Word converters available as SaaS.

The documentation in this section refers to the On-Premises version of the Import and Export to Word which was designed to be easy to set up and maintain (while preserving all the features of a SaaS variant). It also lowers the running costs by reducing the number of servers required to run the whole application to the minimum.

The only requirement to run Import and Export to Word On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.

<a id="cs/latest/onpremises/docx-onpremises/overview.html--next-steps">

### Next steps

Read the [requirements for Import and Export to Word On-Premises](#cs/latest/onpremises/docx-onpremises/requirements.html).  
Read [how to install Import and Export to Word On-Premises](#cs/latest/onpremises/docx-onpremises/installation.html).

<a id="cs/latest/onpremises/docx-onpremises/requirements.html">source file: "cs/latest/onpremises/docx-onpremises/requirements.html"</a>

## Import and Export to Word On-Premises requirements

To run Import and Export to Word On-Premises, you need a Docker environment. Alternatively, you can use a CaaS available from your cloud provider, such as AWS ECS, Google GKE or Azure ACS.

There are many factors that may affect Export to Word On-Premises performance. The most influential are: the size of exported content, the size of images, and the number of concurrent requests. Also, because your application can prioritize fast response times, or it should handle high load, it is impossible to provide one recommended server specification, that will fit all use cases.

Assuming response time below 10 seconds, one server (2CPU 2GB RAM) with 1 docker container can handle:

* up to 45 concurrent requests with an average content of 1 A4 page (\~1k characters)
* up to 30 concurrent requests with an average content of 5 A4 pages (\~7,5k characters)
* up to 10 concurrent requests with an average content of 20 A4 pages (\~30k characters)

<a id="cs/latest/onpremises/docx-onpremises/requirements.html--high-availability">

#### High availability

One docker container with Import and Export to Word On-Premises benefits from additional CPUs on the machine. We recommend 2 CPUs for every docker container. To scale your app on a single machine, you can increase the number of CPUs and docker containers, however, we recommend scaling on at least three hosts to ensure the reliability of the system.

A load balancer, like HAProxy or NGINX (see the load balancer configuration examples in the [SSL communication guide](#cs/latest/onpremises/docx-onpremises/ssl.html)), is required for scaling on several machines. Of course, it is possible to use any cloud provider for scaling, like Amazon ECS, Azure Container Instances or Kubernetes.

[Contact us](https://ckeditor.com/contact/) if you have any questions about server resources needed for your use case of Import and Export to Word On-Premises.

<a id="cs/latest/onpremises/docx-onpremises/ssl.html">source file: "cs/latest/onpremises/docx-onpremises/ssl.html"</a>

## Import and Export to Word On-Premises SSL communication

You can communicate with Import and Export to Word On-Premises using secure connections. To achieve this, you need to set up a load balancer like `NGINX` or `HAProxy` with your SSL certificate.

You can find `HAProxy` and `NGINX` configuration examples below.

<a id="cs/latest/onpremises/docx-onpremises/ssl.html--haproxy-example">

### `HAProxy` example

Here is a basic `HAProxy` configuration:

```
global
    daemon
    maxconn 256
    tune.ssl.default-dh-param 2048

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/your_certificate.pem
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
    redirect scheme https if !{ ssl_fc }

    default_backend servers

backend servers
    server server1 127.0.0.1:8000 maxconn 32

```

<a id="cs/latest/onpremises/docx-onpremises/ssl.html--nginx-example">

### `NGINX` example

Here is a basic `NGINX` configuration:

```
events {
    worker_connections  1024;
}

http {
    server {
        server_name your.domain.name;

        listen 443;
        ssl on;
        ssl_certificate /etc/ssl/your_cert.crt;
        ssl_certificate_key /etc/ssl/your_cert_key.key;

        location / {
            proxy_pass http://127.0.0.1:8000;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
        }
    }
}

```

<a id="cs/latest/onpremises/index.html">source file: "cs/latest/onpremises/index.html"</a>

## CKEditor Cloud Services On-Premises

Welcome to the CKEditor Cloud Services On-Premises. It provides the CKEditor Cloud Services functionality for your own servers, letting the you create a cloud platform including all CKEditor services.

The On-Premises version of [CKEditor Cloud Services](#cs/latest/guides/overview.html) is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It is a highly scalable solution, designed to handle an unlimited number of concurrent connections. Collaboration Server On-premises includes: Collaborative Editing, real-time Comments, real-time Track Changes and Revision History. Subject to additional subscription fee, customers can purchase Revision History feature working in collaborative editing mode.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/overview.html) – An introduction to Cloud Services On-Premises.
* [Collaboration Server](#cs/latest/onpremises/cs-onpremises/overview.html) – Learn how to setup and configure **Collaboration Server** On-Premises.
* [CKBox Server](#cs/latest/onpremises/ckbox-onpremises/overview.html) – Learn how to setup and configure **CKBox** On-Premises.
* [CKEditor AI On-Premises](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html) – Learn how to setup and configure **CKEditor AI** On-Premises.
* [Export to PDF](#cs/latest/onpremises/pdf-onpremises/overview.html) – Learn how to setup and configure **Export to PDF** On-Premises.
* [Import and Export to Word](#cs/latest/onpremises/docx-onpremises/overview.html) – Learn how to setup and configure **Import from Word** and **Export to Word** On-Premises.

<a id="cs/latest/onpremises/overview.html">source file: "cs/latest/onpremises/overview.html"</a>

## Cloud Services On-Premises

Welcome to the CKEditor Cloud Services On-Premises. It provides the CKEditor Cloud Services functionality for your own servers, letting the you create a cloud platform including all CKEditor services.

<a id="cs/latest/onpremises/overview.html--collaboration-server">

### Collaboration Server

The On-Premises version of [CKEditor Cloud Services](#cs/latest/guides/overview.html) is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It is a highly scalable solution, designed to handle an unlimited number of concurrent connections. Collaboration Server On-premises includes: or Collaborative Editing, real-time Comments, real-time Track Changes and Revision History. Subject to additional subscription fee, customers can purchase Revision History feature working in collaborative editing mode.

Learn how to setup and use the [Collaboration Server On-Premises](#cs/latest/onpremises/cs-onpremises/overview.html)

<a id="cs/latest/onpremises/overview.html--ckbox-on-premises">

### CKBox On-Premises

The On-Premises version of the CKBox is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKBox SaaS version.

The CKBox On-Premises is a management platform service that takes care of image and file uploads and reduces the effort required on your part to build a complete modern editing solution with support for embedding images.

Learn how to setup and use the [CKBox On-Premises](#cs/latest/onpremises/ckbox-onpremises/overview.html)

<a id="cs/latest/onpremises/overview.html--ckeditor-ai-on-premises">

### CKEditor AI On-Premises

The On-Premises version of the CKEditor AI is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud.

The CKEditor AI On-Premises leverages AI capabilities inside the CKEditor 5.

Learn how to setup and use the [CKEditor AI On-Premises](#cs/latest/onpremises/ckeditor-ai-onpremises/overview.html)

<a id="cs/latest/onpremises/overview.html--import-and-export-to-word-on-premises">

### Import and Export to Word On-Premises

The Import and Export to Word On-Premises contain the Import from Word and Export to Word features.

The Export to Word feature allows you to generate a `.docx` file directly from the CKEditor 5 WYSIWYG editor content.

When enabled, this feature sends the content of your editor together with the styles that are used to display it to the CKEditor HTML to DOCX converter service. The service then generates a Word document that can be downloaded by the user. This allows you to easily export your content to the Microsoft Word format.

The Import from Word feature allows you to import a `.docx` file directly into the CKEditor 5 WYSIWYG editor content.

It gets `.docx` file, converts it into HTML, CSS and JSON with document content, comments and suggestions, which can be later easily imported into CKEditor 5.

Learn how to set up and use [Import and Export to Word On-Premises](#cs/latest/onpremises/docx-onpremises/overview.html).

<a id="cs/latest/onpremises/overview.html--export-to-pdf-on-premises">

### Export to PDF On-Premises

The Export to Pdf On-Premises feature allows you to generate a PDF file directly from the CKEditor 5 WYSIWYG editor content.

When enabled, this feature sends the content of your editor together with the styles that are used to display it to the CKEditor HTML to PDF converter service. The service then generates a PDF document that can be downloaded by the user. This allows you to easily print your content to the PDF format.

Learn how to set up and use [Export to PDF On-Premises converter](#cs/latest/onpremises/pdf-onpremises/overview.html).

<a id="cs/latest/onpremises/overview.html--cloud-vs-on-premises">

### Cloud vs. On-Premises

CKEditor Cloud Services is available in two variants.

The first one is **Software as a Service (SaaS)**. In this variant, CKSource takes care of all the needed infrastructure, adjusts the servers to the current needs, ensures data safety as well as performs and restores backups in the case of any losses. After completing the purchase, the customer can log into the Customer Portal where they can find all the credentials needed to get up and running with CKEditor Cloud Services. The SaaS environment runs on the AWS infrastructure, which allows us to keep the availability on a high level. You can read more about server security on the [security page](#cs/latest/guides/system-security.html).

The other approach is **On-Premises**, where CKSource provides just the software. It is the customer that is responsible for the installation, provision and maintenance of the servers. In addition, the customer needs to monitor the servers, scale the application in response to the increased usage, as well as take care of creating and restoring backups. Before running CKEditor Cloud Services for the first time, the customer needs to prepare the whole environment, which requires additional work by developers.

<a id="cs/latest/onpremises/overview.html--updates">

#### Updates

New features and fixes are applied to SaaS immediately after being tested, while the On-Premises Docker images are released periodically every 6 weeks and the On-Premises installation has to be updated manually.

<a id="cs/latest/onpremises/overview.html--support-and-monitoring">

#### Support and monitoring

Irrespective of the selected CKEditor Cloud Services variant, CKSource customers are always provided with top-quality assistance. Thanks to the robust monitoring system, the CKSource team is able to swiftly debug SaaS application problems. Support for On-Premises is also provided but, due to the infrastructure being managed on the customer’s end, it requires closer cooperation between CKSource and the client team.

<a id="cs/latest/onpremises/pdf-onpremises/api.html">source file: "cs/latest/onpremises/pdf-onpremises/api.html"</a>

## Export to PDF On-Premises REST API usage

The Export to PDF On-Premises converter provides the ability to convert an HTML document to a PDF file via Restful API.

The API is available on `http://localhost:[port]` (by default the `port` is `8080`).

If you have the authorization for the API enabled, you should provide an authorization token. More instructions you can find in the [authorization](#cs/latest/onpremises/pdf-onpremises/authorization.html) section.

<a id="cs/latest/onpremises/pdf-onpremises/api.html--using-additional-http-headers">

#### Using additional HTTP headers

If fetching some resources (e.g. images) used in a generated PDF requires passing an additional authorization factor in the form of additional HTTP headers:

1. It can be defined on the application startup by setting `EXTRA_HTTP_HEADERS` environmental variable where the value is a stringified JSON object with required headers.
2. It can be defined in a request sent to the PDF Converter API in `options`:

```
const data = {
   html: '<p>I am a teapot</p><img src="https://secured-example-website.com/image.jpg">',
   css: 'p { color: red; }',
   options: {
      extra_http_headers: {
        authorization: 'Bearer RDp0NqyePooNWFIWvHtbKrKKHLXfmLfZcv3PRpCyJI90uwi3pKvumKl2vymCxoGFw6Vx'
      }
   }
};

axios.post( 'https://pdf-converter.cke-cs.com/v1/convert', data, config )
   .then( response => {
      fs.writeFileSync('./file.pdf', response.data, 'binary')
   } ).catch( error => {
      console.log( error );
   } );

```

Headers defined in the application config and from the request are merged. If the same header is defined in both places, a header value from PDF options is prioritized over the value from the application config.

<a id="cs/latest/onpremises/pdf-onpremises/authorization.html">source file: "cs/latest/onpremises/pdf-onpremises/authorization.html"</a>

## Export to PDF On-Premises authorization

To enable authorization, set the `SECRET_KEY` environment variable during the [installation](#cs/latest/onpremises/pdf-onpremises/installation.html).

If the `SECRET_KEY` variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the `Authorization` header for each request sent to the [Export to PDF REST API](#cs/latest/onpremises/pdf-onpremises/api.html).

<a id="cs/latest/onpremises/pdf-onpremises/authorization.html--generating-the-token">

### Generating the token

We highly recommend using the libraries listed on [jwt.io](http://jwt.io/) to generate the token. The token is considered valid, when:

* it is signed with the same `SECRET_KEY` as passed to the Export to PDF On-Premises instance,
* it was created within the last 24 hours,
* it is not issued in the future (e.i. the `iat` timestamp cannot be newer than the current time),
* it has not expired yet.

Tokens for the Export to PDF On-Premises do not require any additional claims such as the environment ID (which is specific for Collaboration Server On-Premises), so you can create the token with an empty payload.

If your use case involves sending requests from your backend server, then you can generate JWT tokens locally, as it is done in our [request example](#cs/latest/onpremises/pdf-onpremises/authorization.html--request-example-with-an-authorization-header).

In the case of editor plugins or other frontend usages, you should create a token endpoint, that returns a valid JWT token for authorized users. Here you can find an example of a [endpoint implementation](#cs/latest/examples/token-endpoints/nodejs.html--export-to-pdf-and-import-and-export-to-word-on-premises).

<a id="cs/latest/onpremises/pdf-onpremises/authorization.html--using-editor-plugins">

### Using editor plugins

Plugins for CKEditor 4 and CKEditor 5 will automatically request the token from the given `tokenUrl` variable and set the `Authorization` header when making an export request. Refer to the [CKEditor 4 configuration guide](https://ckeditor.com/docs/ckeditor4/latest/features/exporttopdf.html#configuration) or [CKEditor 5 configuration guide](#ckeditor5/latest/features/converters/export-pdf.html--installation) for details on adding the Export to PDF feature to your WYSIWYG editor!

<a id="cs/latest/onpremises/pdf-onpremises/authorization.html--request-example-with-an-authorization-header">

### Request example with an Authorization header

The following example presents a request that generates valid JWT token and sets it as `Authorization` header:

```
const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const SECRET_KEY = 'secret';

const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );

const data = {
   html: "<p>I am a teapot</p>",
   css: "p { color: red; }",
};

const config = {
   headers: {
      'Authorization': token
   },
   responseType: 'arraybuffer',
};

axios.post( 'http://localhost:8080/v1/convert', data, config )
   .then( response => {
      fs.writeFileSync('./file.pdf', response.data, 'binary');
   } ).catch( error => {
      console.log( error );
   } );

```

`SECRET_KEY` it’s the key which has been passed to the Export to PDF On-Premises instance

Please refer to the [Export to PDF REST API documentation](https://pdf-converter.cke-cs.com/docs) to start using the service.

Note: If you use API clients like Postman or Insomnia, then set the JWT token as an `Authorization` header in the `Headers` tab. Do not use the built-in token authorization as this will generate invalid header with a `Bearer` prefix added to the token.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html">source file: "cs/latest/onpremises/pdf-onpremises/changelog.html"</a>

## Export to PDF On-Premises

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--201-2026-03-10">

### 2.0.1 (2026-03-10)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--200-2026-02-12">

### 2.0.0 (2026-02-12)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features">

#### Features

\*\*\* Note: \*\*\*  
The `/v2/convert/html-pdf` endpoint has been introduced with this version.  
The `v2` provides a number of new features and optimizations to the Export to PDF feature. All changes mentioned in the changelog apply to the `v2` version.  
In case of any problem or regression, we encourage you to use the previous version and report the discovered problems through the support channel.

* Added header and footer variants for first, odd, and even pages  
Header and footer variants now support images as well.
* Added support for custom page sizes  
The page size can be set to a predefined format or a custom width/height object.
* Added mirror margins  
This allows book-like margins where left and right margins swap between pages.
* Added metadata, password protection, and digital signatures  
You can now set PDF metadata, protect documents with a password, and sign PDFs using a PKCS 12 certificate.
* Enabled PDF compression by default  
Compression can be disabled via `config.disable_compression`.
* Enabled stream processing by default  
This allows for larger payloads compared to v1.
* Reworked request payload shape for v2  
The API is now unified with Export to Word v2, with features grouped by purpose for a tidier, more structured payload. See the migration guide in `/v2/convert/docs#section/Export-to-PDF-(v2)/Migration-guide-from-v1-to-v2`.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-2">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1106-2026-01-15">

### 1.10.6 (2026-01-15)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--bug-fixes">

#### Bug fixes

* Fixed Base URL feature in Stream Processing  
The Base URL feature has been fixed when used with enabled Stream Processing.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-3">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1105-2025-12-03">

### 1.10.5 (2025-12-03)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--bug-fixes-2">

#### Bug fixes

* Fixed broken REST API documentation  
An incomplete endpoint definition caused the documentation to fail when accessing `/docs`.  
The REST API documentation is now available again at `/docs`.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-4">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1104-2025-11-19">

### 1.10.4 (2025-11-19)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-5">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1103-2025-09-23">

### 1.10.3 (2025-09-23)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-6">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1102-2025-07-28">

### 1.10.2 (2025-07-28)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-7">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1101-2025-06-03">

### 1.10.1 (2025-06-03)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-8">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--1100-2025-04-08">

### 1.10.0 (2025-04-08)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-2">

#### Features

* Added support for non-https resource requests  
The converter now allows to request resources over http.  
To enable this feature, the `ALLOW_INSECURE_RESOURCES` environment variable must be set to `true`.  
It is disabled by default for security reasons.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-9">

#### Other changes

* Improved memory consumption  
The converter now consumes less memory while processing large documents.
* Updated node version to 22.14.0  
The node version has been updated to 22.14.0 improving the security, reliability  
and performance of the application.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--190-2025-02-11">

### 1.9.0 (2025-02-11)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-3">

#### Features

* Added STIX Two Math Fonts by default  
The font improves converter’s MathML compliance.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-10">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--180-2024-12-17">

### 1.8.0 (2024-12-17)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-4">

#### Features

* Added support for image merge fields  
Added support for the merge fields within image source attributes, allowing dynamic image references when field values are provided. Note: due to Word limitations, this cannot generate new image fields in the document on its own, you have to provide merge field value via the `merge_fields.data` configuration option.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-11">

#### Other changes

* Updated format field in PDF converter’s options  
Format field in PDF converter’s options is now case insensitive for user’s convenience. For example, from now on both “A4” and “a4” formats will be accepted.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--171-2024-10-01">

### 1.7.1 (2024-10-01)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-12">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--170-2024-08-06">

### 1.7.0 (2024-08-06)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-5">

#### Features

* Added Merge fields support  
The feature allows to provide HTML with placeholders, which will be replaced during conversion with provided options value.  
You can read more in the documentation `/docs#section/PDF-options/Merge-fields`.
* Added support for safe version of Extra HTTP Headers  
The `options.extra_http_headers` allow now to define extra http headers for selected domains.  
The old approach is still supported however it is considered as deprecated.  
You can read more in the documentation `/docs#section/PDF-options/Extra-HTTP-headers`.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-13">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--166-2024-06-19">

### 1.6.6 (2024-06-19)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-14">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--165-2024-04-30">

### 1.6.5 (2024-04-30)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-15">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--164-2024-03-05">

### 1.6.4 (2024-03-05)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-16">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--163-2024-01-09">

### 1.6.3 (2024-01-09)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-17">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--162-2023-11-14">

### 1.6.2 (2023-11-14)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-18">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--161-2023-10-05">

### 1.6.1 (2023-10-05)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-19">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.  
The above update patches the security vulnerability related to the heap buffer overflow risk.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--160-2023-09-19">

### 1.6.0 (2023-09-19)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-6">

#### Features

* Added the `base_url` conversion option  
This option allows setting the base URL for resolving images’ and links’ relative URLs in the content, e.g. setting the `base_url` option to https://ckeditor.com will result in resolving a /docs link as https://ckeditor.com/docs.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-20">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--150-2023-07-25">

### 1.5.0 (2023-07-25)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-7">

#### Features

* Added support for custom headers while fetching external resources  
Custom headers can now be added to every request which fetches external resources.  
It can be used e.g. to authorize access to external resource.  
You will find more information in our documentation.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-21">

#### Other changes

* Improved mechanism of conversion  
The conversion mechanism has been reworked. It will allow to handle bigger payloads and to generate bigger PDFs.  
The mechanism can be enabled by setting the environmental variable.  
To see more details please check our PDF converter On-premises documentation.
* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--146-2023-05-30">

### 1.4.6 (2023-05-30)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-22">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--145-2023-04-04">

### 1.4.5 (2023-04-04)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-23">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--144-2023-02-07">

### 1.4.4 (2023-02-07)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-24">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--143-2022-11-29">

### 1.4.3 (2022-11-29)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-25">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--142-2022-10-18">

### 1.4.2 (2022-10-18)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-26">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--141-2022-09-06">

### 1.4.1 (2022-09-06)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-27">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--140-2022-07-26">

### 1.4.0 (2022-07-26)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-8">

#### Features

* Added possibility to set the origin of external requests  
The change allows configuring CORS for external resources in a proper way.  
To set custom request origin use the `CUSTOM_REQUEST_ORIGIN` environment variable while running Export to PDF On-Premises.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-28">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--131-2022-06-14">

### 1.3.1 (2022-06-14)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-29">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--130-2022-05-05">

### 1.3.0 (2022-05-05)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-9">

#### Features

* Added support for ARM64v8 CPU architecture  
The Export to PDF On-Premises Server can now be run on machines with the ARM64v8 CPU architecture.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-30">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--125-2022-03-22">

### 1.2.5 (2022-03-22)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-31">

#### Other changes

* Updated dependencies  
Updated selected dependencies to the latest versions - improved the performance and security.
* Cleaned up dependencies

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--124-2022-02-08">

### 1.2.4 (2022-02-08)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-32">

#### Other changes

* Updated dependencies  
Updated part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--123-2022-01-18">

### 1.2.3 (2022-01-18)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-33">

#### Other changes

* Update Node.js to version 16
* Updated dependencies  
Updated part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--122-2021-11-16">

### 1.2.2 (2021-11-16)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-34">

#### Other changes

* Updated dependencies  
Updated part of the dependencies to the latest versions - improved the performance and security.  
From this version, the Docker Engine 20.10 or higher is recommended.
* Updated base docker image (Alpine Linux) from version 3.12 to 3.14

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--121-2021-10-05">

### 1.2.1 (2021-10-05)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-35">

#### Other changes

* Updated dependencies  
Updated part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--120-2021-08-24">

### 1.2.0 (2021-08-24)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-10">

#### Features

* Increased maximum size of the HTML  
The service allows converting HTML with a maximum size of the content being 70 MB.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-36">

#### Other changes

* Improved logs readability
* Updated dependencies  
Updated a part of the dependencies to the latest versions - improved the performance and security.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--110-2021-02-25">

### 1.1.0 (2021-02-25)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--bug-fixes-3">

#### Bug fixes

* Handled the case when an invalid external resource link provided  
If the service will not be able to fetch an external resource, the timeout error will be returned.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--documentation">

#### Documentation

* Added the documentation for the `Authorization` HTTP header  
The documentation explains how to use the `Authorization` HTTP header and includes a sample application.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--other-changes-37">

#### Other changes

* Improved the demo page  
The demo page UI and the example document content have been improved.

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--100-2020-07-24">

### 1.0.0 (2020-07-24)

<a id="cs/latest/onpremises/pdf-onpremises/changelog.html--features-11">

#### Features

* Added On-Premises version of PDF Converter  
The service allows to convert HTML into PDF documents via the REST API.
* Added authorization  
JWT authorization can be set with the `SECRET_KEY` environment variable.

<a id="cs/latest/onpremises/pdf-onpremises/fonts.html">source file: "cs/latest/onpremises/pdf-onpremises/fonts.html"</a>

## Export to PDF On-Premises fonts handling

During document writing, the possibility of using many different fonts can be very important to users.

Using the appropriate font can change the appearance of the document and emphasize its style.

PDF Converter allows you to use [Web Fonts](https://pdf-converter.cke-cs.com/docs#section/Web-Fonts), gives you the ability to use standard operating system fonts or use your custom fonts without the need to import them using CSS.

Below is a list of the basic fonts included in the image:

```
OpenSans-Bold.ttf
OpenSans-BoldItalic.ttf
OpenSans-ExtraBold.ttf
OpenSans-ExtraBoldItalic.ttf
OpenSans-Italic.ttf
OpenSans-Light.ttf
OpenSans-LightItalic.ttf
OpenSans-Regular.ttf
OpenSans-Semibold.ttf
OpenSans-SemiboldItalic.ttf

```

However, you can add additional fonts to PDF Converter in two ways:

* Use Unix-like PDF-Converter image `docker.cke-cs.com/pdf-converter` and mount your fonts directory to it. See [Add custom fonts to PDF Converter](#cs/latest/onpremises/pdf-onpremises/fonts.html--add-custom-fonts-to-pdf-converter) section.
* Use Windows PDF-Converter image `docker.cke-cs.com/pdf-converter-windows` and mount to it fonts directory from the Windows operating system on which the container is running. See [Use Windows fonts in PDF Converter](#cs/latest/onpremises/pdf-onpremises/fonts.html--use-windows-fonts-in-pdf-converter) section.

<a id="cs/latest/onpremises/pdf-onpremises/fonts.html--add-custom-fonts-to-pdf-converter">

### Add custom fonts to PDF Converter

If you want to use your custom fonts in your PDF files, you can use the `pdf-converter` Docker image and mount the directory with your custom fonts for the PDF Converter application running on a machine with a Unix-like system (this includes Docker on Windows with a WSL backend).

You just need to run the `docker.cke-cs.com/pdf-converter` Docker image on a Unix-like operating system and mount the `~/your_fonts_dir:/usr/share/fonts/your_fonts_dir` volume.

Launch the Docker container on Unix-like operating system example:

```
docker run --init -v ~/your_fonts_dir:/usr/share/fonts/your_fonts_dir -p 8080:8080 -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/pdf-converter:[version]

```

<a id="cs/latest/onpremises/pdf-onpremises/fonts.html--use-windows-fonts-in-pdf-converter">

### Use Windows fonts in PDF Converter

If you want to use Windows fonts like Arial, Verdana, etc. in your PDF files, you can use `pdf-converter-windows` Docker image that allows you to run the application on a machine with Windows operating system and mount fonts from the system.

You just need to run `docker.cke-cs.com/pdf-converter-windows` Docker image on Windows operating system and mount `C:\Windows\Fonts:C:\Windows\Fonts` volume.

Launch the Docker container on Windows operating system example:

```
docker run -v C:\Windows\Fonts:C:\Windows\Fonts -p 8080:8080 --env LICENSE_KEY=[your_license_key] docker.cke-cs.com/pdf-converter-windows:[version]

```

<a id="cs/latest/onpremises/pdf-onpremises/index.html">source file: "cs/latest/onpremises/pdf-onpremises/index.html"</a>

## Export to PDF On-Premises

The On-Premises version of PDF Converter is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the PDF Converter available as SaaS.

Refer to the following sections for more information:

* [Overview](#cs/latest/onpremises/pdf-onpremises/overview.html) – An introduction to Export to PDF On-Premises.
* [Requirements](#cs/latest/onpremises/pdf-onpremises/requirements.html) – Learn about the prerequisites to install and run Export to PDF On-Premises.
* [Installation](#cs/latest/onpremises/pdf-onpremises/installation.html) – Learn how to install Export to PDF On-Premises.
* [API](#cs/latest/onpremises/pdf-onpremises/api.html) – Learn how to use the HTML to PDF converter REST API.
* [Authorization](#cs/latest/onpremises/pdf-onpremises/authorization.html) – Learn how to add authorization to Export to PDF On-Premises.
* [SSL communication](#cs/latest/onpremises/pdf-onpremises/ssl.html) – Learn how to set up secure communication with Export to PDF On-Premises.
* [Logs](#cs/latest/onpremises/pdf-onpremises/logs.html) – Learn how to manage the logs of Export to PDF On-Premises.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html">source file: "cs/latest/onpremises/pdf-onpremises/installation.html"</a>

## Export to PDF On-Premises installation

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--supported-technologies">

### Supported technologies

The application is provided as a docker image by default.

It can be run with any Open Container runtime tool e.g. [Kubernetes](https://kubernetes.io/), [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift), [Podman](https://podman.io/), [Docker](https://docs.docker.com/) and many others.

Refer to the [Requirements guide](#cs/latest/onpremises/pdf-onpremises/requirements.html) for more information about the hardware and software requirements to run the Export to PDF On-Premises.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--setting-up-the-application-using-kubernetes-with-helm-charts">

### Setting up the application using Kubernetes with Helm charts

Use the provided Helm chart to set up the Export to PDF On-Premises.  
More instructions and the Helm chart you will find [in our repository](https://github.com/cksource/ckeditor-cs-on-premises-infrastructure/tree/main/kubernetes/helm/ckeditor-pdf-converter).

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--setting-up-the-application-using-a-docker-container">

### Setting up the application using a Docker container

1. Use instructions from the [Customer Portal](https://portal.ckeditor.com/) to log into the Export to PDF On-Premises (PDF converter) Docker registry and pull the Docker image.
2. Containerize the application using `docker` or `docker-compose`.
3. Use a demo page to verify if the application works properly.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--containerize-example-using-docker">

#### Containerize example using `docker`

Launch the Docker container:

```
docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] docker.cke-cs.com/pdf-converter:[version]

```

If you want to use authorization you should provide `SECRET_KEY`:

```
docker run --init -p 8080:8080 -e LICENSE_KEY=[your_license_key] -e SECRET_KEY=[your_secret_key] docker.cke-cs.com/pdf-converter:[version]

```

You can read more about using authorization in the [authorization](#cs/latest/onpremises/pdf-onpremises/authorization.html) section.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--containerize-example-using-docker-compose">

#### Containerize example using `docker-compose`

1. Create the `docker-compose.yml` file:

```
version: "3.8"
  services:
    image: docker.cke-cs.com/pdf-converter:[version]
      ports:
        - "8080:8080"
      restart: always
      init: true
      environment:
        LICENSE_KEY: your_license_key
        # Secret Key is optional
        SECRET_KEY: secret_key
        # Custom request origin is optional
        CUSTOM_REQUEST_ORIGIN: https://your_custom_origin

```

For details on `SECRET_KEY` usage check the [authorization](#cs/latest/onpremises/pdf-onpremises/authorization.html) section.

1. Run:

```
docker-compose up

```

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--notes">

### Notes

* Without a correct `LICENSE_KEY` the application will not start. If the license is invalid, you’ll get a `Wrong license key` error in the logs and the application will not run.
* You should override the `SECRET_KEY` variable using a unique and hard to guess string for security reasons.
* If your infrastructure has strict CORS enabled, then you can use the `CUSTOM_REQUEST_ORIGIN` variable to set the origin of requests made by the converter. The default value is `https://pdf-internal`.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--windows-fonts-support">

### Windows fonts support

If you want to use Windows fonts like Calibri, Verdana, etc. in your PDF files, you can use the `pdf-converter-windows` Docker image and run it on a Windows operating system.

See [Fonts](#cs/latest/onpremises/pdf-onpremises/fonts.html) section for more details.

<a id="cs/latest/onpremises/pdf-onpremises/installation.html--next-steps">

### Next steps

Use the <http://localhost:8080/v1/convert> endpoint to export PDF files. Check out the [authorization](#cs/latest/onpremises/pdf-onpremises/authorization.html) section to learn more about tokens and token endpoints.

You can also use the demo page available on <http://localhost:8080/demo> to generate an example PDF file.

Refer to the Export to PDF REST API documentation on <http://localhost:8080/docs> for more details.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html">source file: "cs/latest/onpremises/pdf-onpremises/logs.html"</a>

## Export to PDF On-Premises logs

The logs from Export to PDF On-Premises are written to `stdout` and `stderr`. Most of them are formatted in JSON. They can be used for monitoring or debugging purposes. In production environments, we recommend storing the logs to files or using a distributed logging system (like ELK or CloudWatch).

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--monitoring-export-to-pdf-with-logs">

### Monitoring Export to PDF with logs

To get more insight into how the Export to PDF On-Premises is performing, we built logs that can be used for monitoring. To enable these, just add the `ENABLE_METRIC_LOGS=true` environment variable.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--log-structure">

#### Log structure

The log structure contains the following information:

* `handler` – A unified identifier of action. Use this field to identify calls.
* `traceId` – A unique RPC call ID.
* `tags` – A semicolon-separated list of tags. Use this field to filter metrics logs.
* `data` – An object containing additional information. It might vary between different transports.
* `data.duration` – The request duration in milliseconds.
* `data.transport` – The type of the request transport. It could be `http` or `ws` (websocket).
* `data.status` – The request status. It can be equal to `success`, `fail`, `warning`.
* `data.statusCode` – The response status in HTTP status code standard.

Additionally, for the HTTP transport, the following information is included:

* `data.url` – The URL path.
* `data.method` – The request method.

In case of an error, `data.status` will be equal to `failed` and `data.message` will contain the error message.

An example log for HTTP transport:

```
{
  "level": 30,
  "time": "2021-03-09T11:15:09.154Z",
  "msg": "Request summary",
  "handler": "convertHtmlToPdf",
  "traceId": "85f13d92-57df-4b3b-98bb-0ca41a5ae601",
  "data": {
    "duration": 2470,
    "transport": "http",
    "statusCode": 200,
    "status": "success",
    "url": "/v1/convert",
    "method": "POST"
  },
  "tags": "metrics"
}

```

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--docker">

### Docker

The docker has built-in logging mechanisms that capture logs from the output of the containers. The default logging driver writes the logs to files.

When using this driver, you can use the `docker logs` command to show logs from a container. You can add the `-f` flag to view logs in real time. Refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/logs/) for more information about the `logs` command.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--distributed-logging">

### Distributed logging

If you are running more than one instance of Export to PDF On-Premises, we recommend using a distributed logging system. It allows you to view and analyze logs from all instances in one place.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--aws-cloudwatch-and-other-cloud-solutions">

#### AWS CloudWatch and other cloud solutions

If you are running Export to PDF On-Premises in the cloud, the simplest and recommended way is to use a service that is available at the selected provider. Here are some of the available services:

* AWS – [CloudWatch](https://aws.amazon.com/CloudWatch)
* Google Cloud – [Cloud Logging](https://cloud.google.com/logging)
* Azure – [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/)

To use CloudWatch with AWS ECS, you have to create a log group before and change the log driver to `awslogs`. When the log driver is configured properly, logs will be streamed directly to CloudWatch.

The `logConfiguration` may look similar to this:

```
"logConfiguration": {
  "logDriver": "awslogs",
  "options": {
    "awslogs-region": "us-west-2",
    "awslogs-group": "cksource",
    "awslogs-stream-prefix": "ck-pdf-converter-logs"
  }
}

```

Refer to the [Using the awslogs Log Driver](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using%5Fawslogs.html) article for more information.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--on-premises-solutions">

#### On-Premises solutions

If you are using your own infrastructure or for some reason cannot use the service offered by your provider, you can always use some on-premises distributed logging system.

There are a lot of solutions available, including:

* [ELK](https://www.elastic.co/what-is/elk-stack) \+ [Filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html)  
This is a stack built on top of Elasticsearch, Logstash and Kibana. In this configuration, Elasticsearch stores logs, Filebeat reads logs from Docker and sends them to Elasticsearch, and Kibana is used to view them. Logstash is not necessary because logs are already structured.
* [Fluentd](https://www.fluentd.org/)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/fluentd) to send the logs. It has a built-in frontend, but can also be integrated with Elasticsearch and Kibana for better filtering.
* [Graylog](https://www.graylog.org)  
It uses a dedicated [Docker log driver](https://docs.docker.com/config/containers/logging/gelf) to send the logs. It has a built-in frontend and needs Elasticsearch to store the logs as well as a MongoDB database to store the configuration.

<a id="cs/latest/onpremises/pdf-onpremises/logs.html--example-configuration">

##### Example configuration

The example configuration uses Fluentd, Elasticsearch, and Kibana to capture logs from Docker.

Before running Export to PDF On-Premises, you have to prepare the logging services. For the purposes of this example, Docker Compose is used. Create the `fluentd`, `elasticsearch` and `kibana` services inside the `docker-compose.yml` file:

```
version: '3.7'
services:
  fluentd:
    build: ./fluentd
    volumes:
      - ./fluentd/fluent.conf:/fluentd/etc/fluent.conf
    ports:
      - "24224:24224"
      - "24224:24224/udp"

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:6.8.5
    expose:
      - 9200
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:6.8.5
    environment:
      ELASTICSEARCH_HOSTS: "http://elasticsearch:9200"
    ports:
      - "5601:5601"

```

To integrate Fluentd with Elasticsearch, you first need to install `fluent-plugin-elasticsearch` in the Fluentd image. To do this, create a `fluentd/Dockerfile` with the following content:

```
FROM fluent/fluentd:v1.10-1

USER root

RUN apk add --no-cache --update build-base ruby-dev \
    && gem install fluent-plugin-elasticsearch \
    && gem sources --clear-all

```

Next, configure the input server and connection to Elasticsearch in the `fluentd/fluent.conf` file:

```
<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>
<match *.**>
  @type copy
  <store>
    @type elasticsearch
    host elasticsearch
    port 9200
    logstash_format true
    logstash_prefix fluentd
    logstash_dateformat %Y%m%d
    include_tag_key true
    type_name access_log
    tag_key @log_name
    flush_interval 1s
  </store>
  <store>
    @type stdout
  </store>
</match>

```

Now you are ready to run the services:

```
docker-compose up --build

```

When the services are ready, you can finally start Export to PDF On-Premises.

```
docker run --init -p 8080:8080 \
--log-driver=fluentd \
--log-opt fluentd-address=[Fluentd address]:24224 \
[Your config here] \
docker.cke-cs.com/pdf-converter:[version]

```

Now open Kibana in your browser. It is available at <http://localhost:5601/>. In the first run, you may be asked about creating an index. Use the `fluentd-*` pattern and press the “Create” button. After this step, your logs should appear in the “Discover” tab.

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html">source file: "cs/latest/onpremises/pdf-onpremises/nightly-releases.html"</a>

## Nightly releases

This article describes the purpose and usage of nightly releases of Export to PDF On-Premises images.

Nightly images are released every day. During the automatic release, we run our tests to make sure that these images are working correctly, but unlike stable releases, nightly builds do not go through our full release process and are not tested and approved by our Quality Assurance.

Nightly images include all of the changes that are merged on our development branches. This allows you to access new features or receive fixes faster than with stable on-premises images.

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html--dangers-of-using-nightly-builds">

### Dangers of using nightly builds

Nightly builds are released automatically. By the nature of these images, they should be treated as unstable. Running an On-Premises application using these images may result in some unexpected behaviors, undocumented features or known and unknown defects.

You need to ensure that the versions that you are willing to run are working correctly and will not impact your application negatively. We highly recommend using DEV/UAT environments first and going through the process of quality acceptance on your side, before you use nightly images in production.

By using the nightly builds you accept the risks mentioned in the documentation.

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html--nightly-images-usage">

### Nightly images usage

There is a difference between the usage of nightly and stable releases of Export to PDF On-Premises. Instead of the `pdf-converter` or `pdf-converter-windows` images, you should use the `pdf-converter-nightly` or `pdf-converter-windows-nightly` images. Notice that the version of nightly images also includes a date and a hash. This date part can help you find the latest version of the nightly build. Example usage:

```
version: "2.2"
services:
    pdf-converter-nightly:
        image: docker.cke-cs.com/pdf-converter-nightly:1.6.3-20240227-a846c6d954 # change the version
        ports:
        - "8080:8080"
        # environment variables and other configuration

```

Nightly builds are available only as docker images.

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html--list-of-available-nightly-versions">

### List of available nightly versions

This list shows available versions for `pdf-converter-nightly` images, but the same versions are also available for `pdf-conveter-windows-nightly` images.

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html--nightly-versions">

<a id="cs/latest/onpremises/pdf-onpremises/nightly-releases.html--fetching-the-latest-nightly-version">

### Fetching the latest nightly version

If you want to automate the process of updating your application and automatically use the latest versions of nightly builds you can make a GET request at <https://docker.cke-cs.com/api/versions/pdf-converter-nightly>. This will fetch the JSON with all available versions. Use the date in the version to find the latest image that can be used in your application.

<a id="cs/latest/onpremises/pdf-onpremises/overview.html">source file: "cs/latest/onpremises/pdf-onpremises/overview.html"</a>

## Export to PDF On-Premises - overview

The On-Premises version of the PDF Converter is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the PDF Converter available as SaaS.

The documentation in this section refers to the On-Premises version of the Export to PDF which was designed to be easy to set up and maintain (while preserving all the features of a SaaS variant). It also lowers the running costs by reducing the number of servers required to run the whole application to the minimum.

The only requirement to run Export to PDF On-Premises is a container runtime or orchestration tool e.g. Docker, Kubernetes, Podman.

<a id="cs/latest/onpremises/pdf-onpremises/overview.html--next-steps">

### Next steps

Read the [requirements for Export to PDF On-Premises](#cs/latest/onpremises/pdf-onpremises/requirements.html).  
Read [how to install Export to PDF On-Premises](#cs/latest/onpremises/pdf-onpremises/installation.html).

<a id="cs/latest/onpremises/pdf-onpremises/requirements.html">source file: "cs/latest/onpremises/pdf-onpremises/requirements.html"</a>

## Export to PDF On-Premises requirements

To run Export to PDF On-Premises you need the Docker environment. Alternatively, you can use CaaS available from your cloud provider, like AWS ECS, Google GKE, or Azure ACS.

There are many factors affecting Export to PDF On-Premises performance. The most influential are the size of exported content, the size of images, and the number of concurrent requests. Also, because your application can prioritize fast response times, or it should handle high load, it is impossible to provide one recommended server specification, that will fit all use cases.

Assuming response time below 10 seconds, one server (2CPU 2GB RAM) with 1 docker container can handle:

* up to 40 concurrent requests with an average content of 1 A4 page (\~1k characters and 1 image)
* up to 25 concurrent requests with an average content of 5 A4 pages (\~7,5k characters and 5 images)
* up to 10 concurrent requests with an average content of 20 A4 pages (\~30k characters and 20 images)

<a id="cs/latest/onpremises/pdf-onpremises/requirements.html--high-availability">

#### High availability

One docker container with Export to PDF On-Premises benefits from additional CPUs on the machine. To scale your app on a single machine, you can increase the number of CPUs, however, we recommend scaling on at least three hosts to ensure the reliability of the system.

A load balancer, like HAProxy or NGINX (see the load balancer configuration examples in the [SSL communication guide](#cs/latest/onpremises/pdf-onpremises/ssl.html)), is required for scaling on several machines. Of course, it is possible to use any cloud provider for scaling, like Amazon ECS, Azure Container Instances, or Kubernetes.

[Contact us](https://ckeditor.com/contact/) if you have any questions about server resources needed for your use case of Export to PDF On-Premises.

<a id="cs/latest/onpremises/pdf-onpremises/ssl.html">source file: "cs/latest/onpremises/pdf-onpremises/ssl.html"</a>

## Export to PDF On-Premises SSL communication

You can communicate with Export to PDF On-Premises using secure connections. To achieve this, you need to set up a load balancer like `NGINX` or `HAProxy` with your SSL certificate.

You can find `HAProxy` and `NGINX` configuration examples below.

<a id="cs/latest/onpremises/pdf-onpremises/ssl.html--haproxy-example">

### `HAProxy` example

Here is a basic `HAProxy` configuration:

```
global
    daemon
    maxconn 256
    tune.ssl.default-dh-param 2048

defaults
    mode http
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend http-in
    bind *:80
    bind *:443 ssl crt /etc/ssl/your_certificate.pem
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Proto http if !{ ssl_fc }
    redirect scheme https if !{ ssl_fc }

    default_backend servers

backend servers
    server server1 127.0.0.1:8000 maxconn 32

```

<a id="cs/latest/onpremises/pdf-onpremises/ssl.html--nginx-example">

### `NGINX` example

Here is a basic `NGINX` configuration:

```
events {
    worker_connections  1024;
}

http {
    server {
        server_name your.domain.name;

        listen 443;
        ssl on;
        ssl_certificate /etc/ssl/your_cert.crt;
        ssl_certificate_key /etc/ssl/your_cert_key.key;

        location / {
            proxy_pass http://127.0.0.1:8000;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
        }
    }
}

```

# CKBox

<a id="ckbox/latest/examples/choosing-files.html">source file: "ckbox/latest/examples/choosing-files.html"</a>

## Choosing files

Choosing files with CKBox is possible using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) configuration option, which takes a callback executed after files are chosen. If this option is defined, `Choose` button will be visible in CKBox. After selecting assets and clicking the `Choose` button, the callback is defined in `assets.onChoose` will receive an array of objects representing chosen assets. To read more about these objects’ structure and available helper methods, please refer to the description of [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) option.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: true,
    assets: {
        // Callback executed after choosing assets
        onChoose: (assets) => {
            assets.forEach((asset) => {
                console.log(asset.data.url);
            })
        }
    }
});

```

Click the button below to open CKBox in dialog mode. URLs of the chosen files will be logged **in the console**.

<a id="ckbox/latest/examples/ckeditor-integration.html">source file: "ckbox/latest/examples/ckeditor-integration.html"</a>

## CKEditor 5 integration

<a id="ckbox/latest/examples/ckeditor-integration.html--how-ckbox-enhances-ckeditor-5">

### How CKBox enhances CKEditor 5

CKBox replaces the basic [CKEditor 5](#ckeditor5/latest/features/file-management/ckbox.html) image upload feature. It provides the image and file upload and management capabilities:

* Enables image uploads through drag & drop and paste from the clipboard.
* Transforms the _Image_ toolbar button, allowing the user to quickly upload and insert an image without opening the CKBox UI.
* Adds separate dedicated toolbar buttons to open the CKBox UI to manage and use uploaded files and to edit images from withing CKBox.
* Also adds a separate dedicated image contextual toolbar button for CKBox image editing.

With CKBox you no longer need to write server-side code to upload and scale images or manage uploaded files.

<a id="ckbox/latest/examples/ckeditor-integration.html--demo">

### Demo

The code snippet below presents an integration of CKBox with a rich version of CKEditor 5, inluding a lot but not all available features of the editor. It provides a complex solution for handling images. Try pasting images from the clipboard (Ctrl/Cmd \+ v)directly into the editing area as well as dropping images – the files will be saved on the fly by CKBox.

You can use the toolbar button to open a CKBox window. Then you can manage your files or choose an asset that should be added to the edited content. The image embedded in the editor this way will produce a highly optimized `<picture>` tag. If the image has the description set in its properties in CKBox, the description will be automatically used as an `alt` attribute of the image embedded in the editor.

Use the image contextual toolbar edit button on a selected image to invoke the image editing pane straight from the editor.

Below, you can find the code of the CKBox integration with CKEditor 5 presented above.

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5-premium-features.umd.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5-premium-features.css" />
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/lark.css">
    </head>
    <body>
        <style>
            #container {
                width: 1000px;
                margin: 20px auto;
            }
            .ck-editor__editable[role="textbox"] {
                /* editing area */
                min-height: 200px;
            }
            .ck-content .image {
                /* block images */
                max-width: 80%;
                margin: 20px auto;
            }
        </style>
        <div id="container">
            <div id="editor">
            </div>
        </div>
        <script>
            // This sample still does not showcase all CKEditor 5 features (!)
            // Visit https://ckeditor.com/docs/ckeditor5/latest/features/index.html to browse all the features.
            const {
                ClassicEditor,
                Autoformat,
                Bold,
                Italic,
                Underline,
                BlockQuote,
                Base64UploadAdapter,
                CloudServices,
                CKBox,
                CKBoxImageEdit,
                Essentials,
                FindAndReplace,
                Font,
                Heading,
                Image,
                ImageCaption,
                ImageResize,
                ImageStyle,
                ImageToolbar,
                ImageUpload,
                PictureEditing,
                Indent,
                IndentBlock,
                Link,
                List,
                MediaEmbed,
                Mention,
                Paragraph,
                PasteFromOffice,
                SourceEditing,
                Table,
                TableColumnResize,
                TableToolbar,
                TextTransformation,
                HtmlEmbed,
                CodeBlock,
                RemoveFormat,
                Code,
                SpecialCharacters,
                HorizontalLine,
                PageBreak,
                TodoList,
                Strikethrough,
                Subscript,
                Superscript,
                Highlight,
                Alignment
            } = CKEDITOR;

            const {
                ExportPdf,
                ExportWord
            } = CKEDITOR_PREMIUM_FEATURES;

            ClassicEditor.create( document.querySelector( '#editor' ), {
                licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                plugins: [
                    Autoformat,
                    BlockQuote,
                    Bold,
                    CloudServices,
                    CKBox,
                    Essentials,
                    FindAndReplace,
                    Font,
                    Heading,
                    Image,
                    ImageCaption,
                    ImageResize,
                    ImageStyle,
                    ImageToolbar,
                    ImageUpload,
                    Base64UploadAdapter,
                    Indent,
                    IndentBlock,
                    Italic,
                    Link,
                    List,
                    MediaEmbed,
                    Mention,
                    Paragraph,
                    PasteFromOffice,
                    PictureEditing,
                    SourceEditing,
                    Table,
                    TableColumnResize,
                    TableToolbar,
                    TextTransformation,
                    Underline,
                    HtmlEmbed,
                    CodeBlock,
                    RemoveFormat,
                    Code,
                    SpecialCharacters,
                    HorizontalLine,
                    PageBreak,
                    TodoList,
                    Strikethrough,
                    Subscript,
                    Superscript,
                    Highlight,
                    Alignment,
                    CKBoxImageEdit,
                    ExportPdf,
                    ExportWord
                ],
                toolbar: {
                    items: [
                        'undo', 'redo',
                        '|',
                        'sourceEditing',
                        '|',
                        'exportPDF','exportWord',
                        '|',
                        'findAndReplace', 'selectAll',
                        '|',
                        'heading',
                        '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor',
                        '-',
                        'bold', 'italic', 'underline',
                        {
                            label: 'Formatting',
                            icon: 'text',
                            items: [ 'strikethrough', 'subscript', 'superscript', 'code', '|', 'removeFormat' ]
                        },
                        '|',
                        'specialCharacters', 'horizontalLine', 'pageBreak',
                        '|',
                        'link', 'insertImage', 'ckbox', 'ckboxImageEdit', 'insertTable',
                        {
                            label: 'Insert',
                            icon: 'plus',
                            items: [ 'highlight', 'blockQuote', 'mediaEmbed', 'codeBlock', 'htmlEmbed' ]
                        },
                        'alignment',
                        '|',
                        'bulletedList', 'numberedList', 'todoList',
                        {
                            label: 'Indents',
                            icon: 'plus',
                            items: [ 'outdent', 'indent' ]
                        }
                    ],
                    shouldNotGroupWhenFull: true
                },
                list: {
                    properties: {
                        styles: true,
                        startIndex: true,
                        reversed: true
                    }
                },
                // https://ckeditor.com/docs/ckeditor5/latest/features/headings.html#configuration
                heading: {
                    options: [
                        { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
                        { model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
                        { model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
                        { model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
                        { model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
                        { model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
                        { model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
                    ]
                },
                placeholder: 'Welcome to CKEditor 5 + CKBox!',
                image: {
                    resizeOptions: [
                        {
                            name: 'resizeImage:original',
                            label: 'Default image width',
                            value: null
                        },
                        {
                            name: 'resizeImage:50',
                            label: '50% page width',
                            value: '50'
                        },
                        {
                            name: 'resizeImage:75',
                            label: '75% page width',
                            value: '75'
                        }
                    ],
                    toolbar: [
                        'imageTextAlternative',
                        'toggleImageCaption',
                        '|',
                        'imageStyle:inline',
                        'imageStyle:wrapText',
                        'imageStyle:breakText',
                        '|',
                        'resizeImage'
                    ],
                },
                link: {
                    addTargetToExternalLinks: true,
                    defaultProtocol: 'https://'
                },
                table: {
                    contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ],
                },
                ckbox: {
                    // You need to provide your own token endpoint here
                    // Sign up to CKBox to get one: https://ckeditor.com/ckbox/
                    tokenUrl: 'https://api.ckbox.io/token/demo',
                    theme: 'lark'
                }
            } )
            .then( ( editor ) => {
                window.editor = editor;
            } )
            .catch( ( error ) => {
                console.error( error.stack );
            } );

        </script>
    </body>
</html>

```

To read more about the options available when integrating CKEditor and CKBox, please refer to the [CKEditor integration guide](#ckbox/latest/guides/configuration/ckeditor-integration.html).

<a id="ckbox/latest/examples/display/dialog-mode.html">source file: "ckbox/latest/examples/display/dialog-mode.html"</a>

## Dialog mode

To open CKBox in dialog mode, set the [dialog](#ckbox/latest/guides/configuration/configuration-options.html--dialog) configuration option to `true`. For more verbose configuration this option allows also for passing an object, which allows for more control over the opened dialog window. For details, please refer to the [dialog](#ckbox/latest/guides/configuration/configuration-options.html--dialog) option description.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: true,
    assets: {
        // Callback executed after choosing assets
        onChoose: (assets) => {
            assets.forEach((asset) => {
                console.log(asset.data.url);
            })
        }
    }
});

```

Click on the button below to open CKBox in dialog mode.

<a id="ckbox/latest/examples/display/full-page-mode.html">source file: "ckbox/latest/examples/display/full-page-mode.html"</a>

## Full-page mode

If you want to use CKBox as a full-page application, attach the CKBox instance to the `document.body`.

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <style>
            html, body {
                margin: 0;
                padding: 0;
                height: 100vh;
            }
        </style>
    </head>
    <body>
        <script>
            CKBox.mount(document.body, {
                tokenUrl: 'https://your.token.url'
            });
        </script>
    </body>
</html>

```

[Open example](https://dev.ckbox.io/demo/full-page.html)

<a id="ckbox/latest/examples/display/inline-mode.html">source file: "ckbox/latest/examples/display/inline-mode.html"</a>

## Inline mode

Inline mode is the default working mode of CKBox. In this case, the CKBox instance will be created in the container passed s the first parameter of `CKBox.mount()` method.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url'
});

```

Please note that in inline mode CKBox instance will occupy all the available space, so you might want to restrict with CSS the `width` and the `height` of the container used by CKBox.

<a id="ckbox/latest/examples/index.html">source file: "ckbox/latest/examples/index.html"</a>

## CKBox examples

Check out these live examples of different implementations and customizations of the CKBox file manager.

**See also**

* [Getting started with CKBox](#ckbox/latest/guides/index.html) – Setting up your copy of CKBox, configuring it, and integrating it with CKEditor 5 and popular frameworks.
* [CKBox features](#ckbox/latest/features/index.html) – Using and administration of the CKBox file manager on a daily basis
* [Support](#ckbox/latest/support/index.html) – Getting help

<a id="ckbox/latest/examples/ui/custom-category-icons.html">source file: "ckbox/latest/examples/ui/custom-category-icons.html"</a>

## Custom category icon

If you want to change the default category icon, use the [categories.icons](#ckbox/latest/guides/configuration/configuration-options.html--categoriesicons) configuration option.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: true,
    categories: {
        icons: {
            Images: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M12.395 2.553a1 1 0 00-1.45-.385c-.345.23-.614.558-.822.88-.214.33-.403.713-.57 1.116-.334.804-.614 1.768-.84 2.734a31.365 31.365 0 00-.613 3.58 2.64 2.64 0 01-.945-1.067c-.328-.68-.398-1.534-.398-2.654A1 1 0 005.05 6.05 6.981 6.981 0 003 11a7 7 0 1011.95-4.95c-.592-.591-.98-.985-1.348-1.467-.363-.476-.724-1.063-1.207-2.03zM12.12 15.12A3 3 0 017 13s.879.5 2.5.5c0-1 .5-4 1.25-4.5.5 1 .786 1.293 1.371 1.879A2.99 2.99 0 0113 13a2.99 2.99 0 01-.879 2.121z" /></svg>',
            // Category can be referenced by ID
            // 'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': '<svg...'
        }
    }
});

```

Click the button below to open the CKBox instance with a fancy flame icon set for the `Images` category.

<a id="ckbox/latest/examples/ui/ui-customization.html">source file: "ckbox/latest/examples/ui/ui-customization.html"</a>

## Changing UI colors

In the simplest case, you might want to change the color palette of CKBox. This can be achieved with a couple of CSS variables. To read more about the available UI customization options, please refer to the [Theming guide](#ckbox/latest/guides/configuration/theming.html).

<a id="ckbox/latest/examples/ui/ui-language.html">source file: "ckbox/latest/examples/ui/ui-language.html"</a>

## Changing the language

The language of the CKBox UI can be changed using the [language](#ckbox/latest/guides/configuration/configuration-options.html--language) configuration option.

In the example below, CKBox is configured to use Spanish.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    language: 'es'
});

```

<a id="ckbox/latest/examples/ui/ui-language.html--ckeditor-integration">

### CKEditor integration

If you are integrating CKBox with CKEditor, please have a look at the example below, which sets the language to Spanish for both, CKEditor and CKBox simultaneously.  
To read more about the integration between CKEditor and CKBox, please refer to the [CKEditor integration guide](#ckbox/latest/guides/configuration/ckeditor-integration.html).

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/translations/es.umd.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/lark.css">
    </head>
    <body>
        <div id="editor"></div>
        <script>
            const {
                ClassicEditor,
                BlockQuote,
                Bold,
                CKBox,
                CloudServices,
                Essentials,
                Heading,
                Image,
                ImageUpload,
                Indent,
                IndentBlock,
                Italic,
                Link,
                List,
                Paragraph,
                PictureEditing
            } = CKEDITOR;

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    ckbox: {
                        tokenUrl: 'https://your.token.url'
                    },
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    plugins: [
                        CKBox, Essentials, Bold, Italic, Heading, Paragraph, ImageUpload,
                        CloudServices, PictureEditing, Link, Image, List, BlockQuote, Indent, IndentBlock
                    ],
                    language: 'es',
                    toolbar: [
                        'ckbox', 'imageUpload', '|',
                        'heading', '|',
                        'undo', 'redo', '|',
                        'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|',
                        'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
        <script>
            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    language: 'es',
                    ckbox: {
                        tokenUrl: 'https://your.token.url'
                    },
                    toolbar: [
                        'ckbox', '|',
                        'undo', 'redo', '|',
                        'imageUpload', '|',
                        'heading', '|',
                        'bold', 'italic'
                    ]
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

As you can see in the example above, the `language` option for CKBox was omitted. This was intentional because by default the language of CKBox will match the language of CKEditor, which has been already set to Spanish. Setting language again in `ckbox.language` would be superfluous in this case.

Below you can see a live example of the configuration presented above.

<a id="ckbox/latest/features/accessibility/accessibile-images.html">source file: "ckbox/latest/features/accessibility/accessibile-images.html"</a>

## Accessible images

<a id="ckbox/latest/features/accessibility/accessibile-images.html--responsive-images-for-all-viewports">

### Responsive images for all viewports

By employing [responsive images](#ckbox/latest/features/images/responsive-images.html), CKBox makes them accessible via a wide range of end-user devices, from smartphones to large displays. Serving an image most suitable to the end-user device saves bandwidth and makes the page load faster.

<a id="ckbox/latest/features/accessibility/accessibile-images.html--text-alternative">

### Text alternative

Thanks to the [asset metadata](../file-management/assets/metadata.html#description), images can also become accessible for screen readers used by persons with sight impairments. The images embedded from CKBox in CKEditor 5 have [their alt attribute](#ckeditor5/latest/features/images/images-text-alternative.html) automatically set based on the **Description** field of the asset. It improves the accessibility of the produced content and saves time and workload for content creators, who do not need to do it by hand.

<a id="ckbox/latest/features/accessibility/conformance-with-wcag.html">source file: "ckbox/latest/features/accessibility/conformance-with-wcag.html"</a>

## Conformance with WCAG 2.x and Section 508

CKBox is compliant with [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) (WCAG) 2.2 levels A and AA and [Section 508 of the Rehabilitation Act](https://www.access-board.gov/ict/) unless stated otherwise in the Accessibility Conformance Report.

* Web Content Accessibility Guidelines 2.2 (WCAG) provides international standards for making web content accessible to individuals with disabilities, ensuring that web applications are perceivable, operable, understandable, and robust for all users.
* Section 508 of the Rehabilitation Act mandates that federal agencies’ electronic and information technology is accessible to people with disabilities, establishing guidelines to achieve this goal.

CKBox strives for conformance with these standards and we welcome your feedback on the accessibility of our software.

<a id="ckbox/latest/features/accessibility/keyboard-shortcuts.html">source file: "ckbox/latest/features/accessibility/keyboard-shortcuts.html"</a>

## Keyboard shortcuts

CKBox supports an extensive set of keyboard shortcuts to make common operations faster and more effective. Keyboard navigation between categories, folders, and individual assets as well as keyboard support for operations such as copying, moving, or deletion of items is a convenient alternative also for users who cannot use pointer devices.

Below is a list of the most important keystrokes supported by CKBox.

<a id="ckbox/latest/features/accessibility/keyboard-shortcuts.html--asset-operations">

### Asset operations

| Action                                                                             | PC                     | Mac              |
| ---------------------------------------------------------------------------------- | ---------------------- | ---------------- |
| Navigate between assets                                                            | ↑ / → / ↓ / ←          |                  |
| Go to the next asset(retaining focus on the currently selected)                    | Tab                    |                  |
| Select multiple assets                                                             | Shift \+ ↑ / → / ↓ / ← |                  |
| Ctrl \+ LMB                                                                        | Cmd \+ LMB             |                  |
| Select a range of assets(from the focused one to the clicked one)                  | Shift+LMB              |                  |
| Select all assets                                                                  | Ctrl \+ A              | Cmd \+ A         |
| Open the selected item to view in fullscreen mode(in standalone file manager mode) | Enter                  |                  |
| Insert the selected item into the editor(when integrated with CKEditor 5)          | Enter                  |                  |
| Close fullscreen view                                                              | Escape                 |                  |
| Copy selected asset(s)                                                             | Ctrl \+ C              | Cmd \+ C         |
| Cut selected asset(s)                                                              | Ctrl \+ X              | Cmd \+ X         |
| Paste asset(s)                                                                     | Ctrl \+ V              | Cmd \+ V         |
| Delete selected asset(s)                                                           | Delete                 | Cmd \+ Backspace |

<a id="ckbox/latest/features/accessibility/keyboard-shortcuts.html--category-and-folder-operations">

### Category and folder operations

| Action                                                                       | PC    | Mac |                                                     |       |
| ---------------------------------------------------------------------------- | ----- | --- | --------------------------------------------------- | ----- |
| Navigate between categories or folders                                       | ↑ / ↓ |     |                                                     |       |
| Go to the next category or folder(retaining focus on the currently selected) | Tab   |     | Expand or collapse a highlighted category or folder | → / ← |
| Enter the focused category or folder                                         | Enter |     |                                                     |       |

<a id="ckbox/latest/features/accessibility/keyboard-shortcuts.html--other-shortcuts">

### Other shortcuts

| Action                                                                                                                         | PC     | Mac   |
| ------------------------------------------------------------------------------------------------------------------------------ | ------ | ----- |
| Invoke the search panel                                                                                                        | Ctrl+F | Cmd+F |
| Run search for the entered phrase                                                                                              | Enter  |       |
| Discard changes and leave editing tools without savingLeave the save dialog and return to editing tools(in image editing mode) | Escape |       |

<a id="ckbox/latest/features/administration-panel.html">source file: "ckbox/latest/features/administration-panel.html"</a>

## Administration panel

Access to the administration panel of CKBox is available only to users with the `admin` role set in the token. To read more about the user roles available, please refer to the [User roles](#ckbox/latest/guides/configuration/authentication.html--user-roles) section.

All the settings configured in the administration panel of CKBox are stored per [environment](#ckbox/latest/guides/configuration/authentication.html--creating-environment).

<a id="ckbox/latest/features/administration-panel.html--choosing-a-workspace-to-manage">

### Choosing a workspace to manage

If your CKBox asset manager utilizes [workspaces](#ckbox/latest/features/file-management/workspaces.html), the settings described below can be separately set for each workspace. Choose a workspace from the top-left dropdown first, then hit the **Settings** button located at the bottom left.

To access these settings, the user needs the [superadmin](#ckbox/latest/guides/configuration/authentication.html--user-roles) privileges.

<a id="ckbox/latest/features/administration-panel.html--category-management">

### Category management

A fresh CKBox environment has three preconfigured asset categories: **Files**, **Images**, and **Documents**. You can create more categories in the **Asset categories** management panel. The categories listed in this section correspond to the list of categories displayed in the left column of CKBox.

<a id="ckbox/latest/features/administration-panel.html--creating-a-new-category">

#### Creating a new category

Clicking the **+** button in the top-right corner of the category management section will create an empty placeholder for a new category. You will be asked to define two things for the newly created category:

* **Category name** – A unique name displayed as the label on the list of asset categories in the left column.
* **Allowed extensions** – The list of file extensions allowed in this category. Only files with extensions allowed here can be uploaded to this category.

If you change your mind at any time later, you will be able to edit all this information by [editing the asset category](#ckbox/latest/features/administration-panel.html--editing-a-category).

Unique category icons are automatically assigned only for categories from the default set (**Files**, **Documents**, and **Images**). All others will use a default category icon. If you would like to assign a custom icon for the category you have created, check the [categories.icons](#ckbox/latest/guides/configuration/configuration-options.html--categoriesicons) configuration option.

<a id="ckbox/latest/features/administration-panel.html--editing-a-category">

#### Editing a category

An existing asset category can be edited at any given time. You can change its name and the list of allowed file extensions.

<a id="ckbox/latest/features/administration-panel.html--file-extensions-in-use">

##### File extensions in use

If you edit a category that contains any files, the file extensions in use will be marked in bold on the list of allowed extensions. Removing extensions in use from the list of allowed extensions will permanently delete all the files that use the removed extensions from the category. To avoid accidental data removal, a confirmation dialog will be displayed. You will be asked to type the category name to confirm the operation.

<a id="ckbox/latest/features/administration-panel.html--changing-the-category-position">

#### Changing the category position

The order of the categories on the list in the **Asset categories** section matches the order displayed in the left column of CKBox. Changing the order of categories in the management panel will have an immediate effect on the list of categories presented to regular users. To change the category position, click on the category drag handle and move it to the target position.

<a id="ckbox/latest/features/administration-panel.html--removing-a-category">

#### Removing a category

To remove a category, locate it on the list in the **Asset categories** administration panel section, and click the **Delete** button. When a category is removed, all its assets will be permanently lost. To avoid accidental data removal, a confirmation dialog will be displayed. You will be asked to type the category name to confirm the operation.

<a id="ckbox/latest/features/administration-panel.html--image-management">

### Image management

In the **Images** section of the administration panel, you can fine-tune the quality of the rescaled versions of images produced by CKBox. There are five predefined compression settings available.

The rescaled versions are used when embedding an image into the CKEditor editing area with the [CKBox plugin for CKEditor](#ckbox/latest/guides/configuration/ckeditor-integration.html). In this case, URLs to different image sizes are used to produce a highly optimized `<picture>` element.

If the image has the description set in its properties in CKBox, it will be automatically used as an `alt` attribute of the image embedded in the editor.

The default quality of responsive images is set to **High**. Lowering the quality will lower the network traffic and your web pages may load faster, although the visual quality of the images might be noticeably lower. If you are not sure which quality to choose, we recommend keeping it set to **High**.

<a id="ckbox/latest/features/ai-features.html">source file: "ckbox/latest/features/ai-features.html"</a>

## AI Features

CKBox AI Features leverage generative artificial intelligence to automatically enhance your asset management workflow. This feature automatically generates descriptive tags and detailed descriptions for all image-like assets, making your content more discoverable and organized without manual effort.

<a id="ckbox/latest/features/ai-features.html--how-ai-features-work">

### How AI Features work

The AI-powered metadata generation is seamlessly integrated into your upload workflow. When you upload image files (such as JPG, PNG, WebP, and other non-animated image formats), CKBox automatically analyzes the visual content using AI to:

* **Generate descriptive tags** that accurately describe the content, objects, colors, and context visible in the image
* **Create detailed descriptions** that provide comprehensive information about the image content, enhancing accessibility and searchability
* **Enable semantic search** by building an internal representation of each image’s visual content, allowing you to later find assets by describing what they depict in natural language

This process happens automatically in the background during file upload, requiring no additional user interaction.

AI analysis is also triggered when images are edited and saved as new files, since the visual content and context may have changed significantly.

<a id="ckbox/latest/features/ai-features.html--enabling-ai-features">

### Enabling AI Features

AI Features are opt-in, meaning they must be explicitly enabled by a workspace administrator. This gives you full control over when and how AI processing is applied to your assets.

<a id="ckbox/latest/features/ai-features.html--administrator-setup">

#### Administrator setup

To enable AI Features for your workspace:

1. Navigate to **Settings** in the left sidebar
2. Select the **AI Features** tab
3. Toggle **AI Access** to enable the feature

Once enabled, all new image uploads will automatically have AI-generated tags and descriptions applied.

<a id="ckbox/latest/features/ai-features.html--viewing-ai-generated-metadata">

### Viewing AI-generated metadata

After uploading images with AI Features enabled, you can view the automatically generated tags and descriptions through the asset properties panel:

1. Select any image asset in your workspace
2. Click the **Properties** icon in the top toolbar
3. Navigate to the **Asset Properties** drawer that appears on the right side
4. View the AI-generated tags in the **Tags** section and description in the **Description** field

The AI-generated content can be edited or removed just like manually added metadata, giving you full control over your asset descriptions.

<a id="ckbox/latest/features/ai-features.html--semantic-search">

### Semantic search

CKBox offers a semantic search capability that goes beyond traditional keyword matching. While the standard search finds assets by matching your query against filenames, descriptions, and tags, semantic search uses AI to understand the meaning behind your query and match it against the visual content of your assets. This means you can describe what you are looking for in natural language – for example, searching for “a sunset over the ocean” will return relevant images even if none of their filenames, tags, or descriptions contain those exact words.

Semantic search works by analyzing the visual content of image-like assets when they are uploaded and creating an internal representation that captures what the image depicts. When you enter a search query, the AI compares the meaning of your query against these representations to find the most relevant results.

<a id="ckbox/latest/features/ai-features.html--using-semantic-search">

#### Using semantic search

To use semantic search, follow these steps:

1. Ensure that **AI Access** is enabled for your workspace. Navigate to **Settings** → **AI Features** and verify the toggle is on. See the [Enabling AI Features](#ckbox/latest/features/ai-features.html--enabling-ai-features) section for details.
2. Open the search dialog by clicking the **magnifying glass** icon in the toolbar.
3. Toggle the **AI search** option to enable semantic search mode.
4. Enter a descriptive phrase for what you are looking for and run the search.

The results will display assets whose visual content best matches the meaning of your query, ranked by relevance.

<a id="ckbox/latest/features/ai-features.html--benefits-of-ai-features">

### Benefits of AI Features

Implementing AI Features in your CKBox workspace provides several key advantages:

<a id="ckbox/latest/features/ai-features.html--enhanced-discoverability">

#### Enhanced discoverability

* **Improved search results**: AI-generated tags make assets easier to find through CKBox’s search functionality
* **Better categorization**: Automatic tagging helps organize assets without manual effort
* **Content-based discovery**: Users can find images by describing what they’re looking for
* **Semantic search**: Find assets by meaning rather than exact keywords — describe what you need in natural language and let AI match it against the visual content of your images

<a id="ckbox/latest/features/ai-features.html--accessibility-improvements">

#### Accessibility improvements

* **Automatic alt text**: AI-generated descriptions enhance accessibility for screen readers and assistive technologies
* **SEO benefits**: Rich metadata improves search engine optimization for web content
* **Compliance support**: Helps meet accessibility standards and requirements

<a id="ckbox/latest/features/ai-features.html--time-and-cost-savings">

#### Time and cost savings

* **Reduced manual work**: Eliminates the need for manual tagging and description writing
* **Consistent metadata**: Ensures all images have descriptive information
* **Scalable solution**: Works efficiently regardless of the number of assets uploaded

<a id="ckbox/latest/features/ai-features.html--content-management-efficiency">

#### Content management efficiency

* **Better organization**: Assets are automatically categorized and tagged
* **Improved workflows**: Content creators can focus on creation rather than metadata management
* **Enhanced collaboration**: Team members can easily find and understand asset content

<a id="ckbox/latest/features/ai-features.html--supported-file-formats">

### Supported file formats

AI Features currently support the following image formats:

* **JPEG** (.jpg, .jpeg)
* **PNG** (.png)
* **WebP** (.webp)
* **BMP** (.bmp)
* **TIFF** (.tiff, .tif)

<a id="ckbox/latest/features/file-management/categories.html">source file: "ckbox/latest/features/file-management/categories.html"</a>

## Managing categories

Categories are the top-level element of the file management structure. They divide assets kept in CKBox into sections based on the type of files uploaded, such as photos or documents. CKBox comes preconfigured with three asset categories: **Files**, **Images**, and **Documents**.

<a id="ckbox/latest/features/file-management/categories.html--browsing-categories">

### Browsing categories

You can browse the categories with a pointing device or keyboard. It is possible to move the focus not only using the standard Tab key but also in a more convenient way by using the arrow keys:

* ↑ and ↓ move the focus along the category tree.
* ← and → expand and collapse the focused folder.
* Enter selects the focused item.

<a id="ckbox/latest/features/file-management/categories.html--creating-updating-and-deleting-categories">

### Creating, updating, and deleting categories

Unlike folders, managing categories in CKBox is only available for users granted the `admin` role. For more detailed information about category management, refer to the [Category management](#ckbox/latest/features/administration-panel.html--category-management) section of the [Administration panel](#ckbox/latest/features/administration-panel.html) guide.

<a id="ckbox/latest/features/file-management/categories.html--file-search">

### File search

Refer to the [Searching](assets/search.html) guide for more details about the search option.

<a id="ckbox/latest/features/file-management/folders.html">source file: "ckbox/latest/features/file-management/folders.html"</a>

## Managing folders

Folders are a key feature of a good file manager. They allow users to organize files in a structured hierarchical manner, easier to search and navigate. Folders are contained within the [categories](#ckbox/latest/features/file-management/categories.html), providing additional sorting levels inside these. They can be created and managed by the users.

<a id="ckbox/latest/features/file-management/folders.html--browsing-folders">

### Browsing folders

You can browse the folders with a pointing device such as a mouse.

Keyboard navigation in the category and folder trees is also available. It is possible to move the focus not only using the standard Tab key but also in a more convenient way by using the arrow keys:

* ↑ and ↓ move the focus along the folder tree.
* ← and → expand and collapse the focused folder.
* Enter selects the focused item.

<a id="ckbox/latest/features/file-management/folders.html--creating-updating-and-deleting-folders">

### Creating, updating, and deleting folders

All folder operations can be easily carried out using the top bar UI elements in the main CKBox area, visible after selecting a folder.

<a id="ckbox/latest/features/file-management/folders.html--adding-a-new-folder">

#### Adding a new folder

To add a new folder, press the **Add folder** button. A pop-up dialog will appear, letting you name the new folder.

<a id="ckbox/latest/features/file-management/folders.html--deleting-a-folder">

#### Deleting a folder

Use the **Delete folder** in the top bar to remove a folder. A confirmation pop-up will appear before deletion. All the folder contents will be moved one level up in the folder hierarchy.

<a id="ckbox/latest/features/file-management/folders.html--renaming-a-folder">

### Renaming a folder

Use the **Rename folder** button in the top bar to rename it. The button might be hidden under the three-dot dropdown menu on narrow viewports, as pictured in the screenshots.

<a id="ckbox/latest/features/file-management/folders.html--uploading-files-and-folders">

### Uploading files and folders

Use the **Upload** button in the top-right corner of the navigation bar to upload new assets into the selected folder. A system dialog will appear, letting you choose the files you want to upload.

The **Upload** button dropdown arrow will let you choose either uploading individual files or whole folders. When uploading folders, they will be added to the CKBox folder structure, accessible from the folder navigation pane on the left.

You can also upload folders by dragging them from your system into the CKBox work area.

<a id="ckbox/latest/features/file-management/folders.html--folder-properties">

### Folder properties

The **Folder information** toolbar button brings up a folder information pane on the right-hand side of the main CKBox area. It provides information about the total number of files in the folder and allowed file formats (refer to the [Administration panel](#ckbox/latest/features/administration-panel.html--file-extensions-in-use) guide for more details on how to set these). It also names the recently added or modified assets and informs about the available limits, such as the maximum file size and allowed resolution.

<a id="ckbox/latest/features/file-management/folders.html--display-options">

### Display options

The **Display options** dialog lets the user control the interface.

Files can be sorted in ascending or descending order by name, size, upload date, or modification date.

You can also set the number of files to display per page here. Predefined values are 50, 100, and 250.

The last option allows choosing the thumbnail size with a convenient slider. You can also decide whether the assets should be displayed keeping the aspect ratio.

<a id="ckbox/latest/features/file-management/folders.html--file-search">

### File search

Refer to the [Searching](assets/search.html) guide for more details about the search option.

<a id="ckbox/latest/features/file-management/overview.html">source file: "ckbox/latest/features/file-management/overview.html"</a>

## File management

CKBox supports storing all types of media: responsive images, documents, various video and audio formats, and more. It offers numerous options not only in terms of supported files but also in how they are stored. Administrators can create specific asset [categories](#ckbox/latest/features/file-management/categories.html) and choose the file formats they want to include.

Once uploaded, assets can be put under predefined categories and assigned to user-created [folders](#ckbox/latest/features/file-management/folders.html). These can be quickly browsed, added, renamed, or moved. Users can also upload folders full of files with a single click.

It is enough to click any file to get a list of [its properties](assets/metadata.html), such as the upload date and size, its dimensions, and the URL to access it. The assets can also be easily [renamed](assets/metadata.html#name), [tagged](assets/metadata.html#tags), or [described](assets/metadata.html#description).

All files can be [easily searched](assets/search.html) using various advanced criteria.

<a id="ckbox/latest/features/file-management/overview.html--demo">

### Demo

<a id="ckbox/latest/features/file-management/overview.html--data-separation-between-users">

### Data separation between users

To establish distinct storage and data segregation among users, user groups, or for seamless integration of CKBox in a multi-tenant application, please refer to the comprehensive guidelines outlined in the [Workspaces](#ckbox/latest/features/file-management/workspaces.html) feature guide.

<a id="ckbox/latest/features/file-management/workspaces.html">source file: "ckbox/latest/features/file-management/workspaces.html"</a>

## Workspaces

CKBox Workspaces provide a convenient solution for achieving data isolation and user separation within CKBox. With workspaces, you can easily create separate storage and data spaces, giving you precise control over assigning specific users, user groups, or tenants to each workspace.

This guide offers general instructions on configuring individual CKBox instances, that can be tailored to meet the requirements of storage and data management.

<a id="ckbox/latest/features/file-management/workspaces.html--managing-workspaces">

### Managing workspaces

Managing workspaces in CKBox is only available for users granted the [superadmin](#ckbox/latest/guides/configuration/authentication.html--user-roles) role. When [creating the JWT token](#ckbox/latest/guides/configuration/authentication.html--token-payload) for authorization, please make sure the proper user role is set in the `auth.ckbox.role` field:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "sub": "example-user-id",
    "iat": 1511963669,
    "auth": {
        "ckbox": {
            "role": "superadmin"
        }
    }
}

```

<a id="ckbox/latest/features/file-management/workspaces.html--managing-workspaces-through-the-administration-panel">

#### Managing workspaces through the administration panel

Workspaces can also be easily managed – created, deleted, or renamed – directly from the administration panel. To access these settings, the user needs the `superadmin` role.

The top-left workspaces dropdown lets the admin choose the workspace to [manage and set up](#ckbox/latest/features/administration-panel.html). The top-right **Superadmin** button lets the user manage workspaces. Entering this area will display a full list of currently available workspaces with tools to add, remove, or rename them.

<a id="ckbox/latest/features/file-management/workspaces.html--searching-workspaces">

##### Searching workspaces

You can search for workspaces by entering their name or by pasting their workspace ID into the search field. The search starts after at least 2 characters have been entered.

The search field filters workspaces by their name, displaying matching results in the sidebar.

Paste a workspace ID directly into the search field to quickly locate a specific workspace.

<a id="ckbox/latest/features/file-management/workspaces.html--creating-workspaces">

##### Creating workspaces

Using the top-right **Add workspace** button will invoke the **Add workspace** dialog.

Enter the desired name for the new workspace and hit **Save**. The new workspace will appear at the top of the list when using default sorting by creation date.

Due to the fact, that every workspace has a unique workspace ID (displayed next to the workspace name) it is possible to name two or more workspaces the same. This, however, may cause confusion between users.

<a id="ckbox/latest/features/file-management/workspaces.html--renaming-workspaces">

##### Renaming workspaces

Using the context menu (accessed via the actions button right to the workspace’s name) and selecting **Rename workspace** will invoke a dialog.

Enter the new name for the workspace and hit **Save**. The renamed workspace will replace the old name on the list.

<a id="ckbox/latest/features/file-management/workspaces.html--deleting-workspaces">

##### Deleting workspaces

If you want to remove a workspace, use the context menu (accessed via the actions button right to the workspace’s name) and select **Delete workspace** option. It will invoke the **Delete workspace** dialog.

To complete deletion, you need to type the workspace’s name first and hit the **Delete button**. It is a safety measure to avoid accidental deletion, as **deleted workspaces cannot be restored**.

<a id="ckbox/latest/features/file-management/workspaces.html--managing-workspaces-with-the-rest-api">

#### Managing workspaces with the REST API

You can automate the process of workspace management using the [REST API](#ckbox/latest/features/rest-api.html).

<a id="ckbox/latest/features/file-management/workspaces.html--creating-updating-and-deleting-workspaces">

##### Creating, updating, and deleting workspaces.

CKBox REST API offers a couple of endpoints that allow for workspace management:

* [GET /v3/workspaces](https://api.ckbox.io/api/docs#tag/Workspaces/operation/getWorkspacesV3)  
This API endpoint returns the list of workspaces available to the user. For the `superadmin` role, it will return a list of all workspaces existing in the workspace environment.
* [POST /superadmin/workspaces](https://api.ckbox.io/api/docs#tag/Workspaces/operation/postWorkspace)  
You can create new workspaces using this endpoint. When the workspace is successfully created, the workspace ID will be returned in the response.
* [PUT /superadmin/workspaces/{workspaceId}](https://api.ckbox.io/api/docs#tag/Workspaces/operation/putWorkspace)  
This endpoint allows modifying an existing workspace, identified by the given workspace ID.
* [DELETE /superadmin/workspaces/{workspaceId}](https://api.ckbox.io/api/docs#tag/Workspaces/operation/deleteWorkspace)  
This endpoint deletes an existing workspace, identified by the given workspace ID. When the workspace is removed, all the assets stored in it are deleted.

<a id="ckbox/latest/features/file-management/workspaces.html--defining-category-templates">

### Defining category templates

Workspaces come with default storage categories which are Files, Documents and Images. With Category Templates, `superadmin` users can define the overall structure of a workspace and control the default set of categories for newly created workspaces automatically.  
If you want, you can use Category Templates to define what categories should be created alongside new workspaces. You can access these settings using **Category templates** tab.

<a id="ckbox/latest/features/file-management/workspaces.html--creating-a-category-template">

#### Creating a category template

Using the top-right **+** button will create an empty placeholder for a new category template. You will be asked to define two things for the newly created category template:

* **Category template name** – A unique name for categories created by this template.
* **Allowed extensions** – The list of file extensions available in categories created using this category template.

If you change your mind at a later time, you can edit all this information by [editing the category template](#ckbox/latest/features/file-management/workspaces.html--editing-a-category-template)

<a id="ckbox/latest/features/file-management/workspaces.html--editing-a-category-template">

#### Editing a category template

An existing category template can be edited at any time. You can change its name and the list of allowed file extensions.

<a id="ckbox/latest/features/file-management/workspaces.html--changing-the-category-template-order">

#### Changing the category template order

The order of the category templates on the list in the **Category templates** section matches the order of categories that will be created with a new workspace. To change the category template position, click on the drag handle to the left, and move it to the target position.

<a id="ckbox/latest/features/file-management/workspaces.html--removing-a-category-template">

#### Removing a category template

To remove a category template, locate it on the list, and click the **Delete** button. A confirmation dialog will be displayed and you will be asked to confirm the operation.

<a id="ckbox/latest/features/file-management/workspaces.html--globally-limiting-extensions">

### Globally limiting extensions

In the **Allowed extensions** tab of the administration panel, you can limit what extensions are allowed to be used.  
If the **Globally limit extensions** option is enabled, only files with extensions specified here will be allowed to be uploaded. In addition, **Category** settings will only permit extensions listed here, to be added as **Allowed extensions**.

<a id="ckbox/latest/features/file-management/workspaces.html--enabling-limited-extensions">

#### Enabling limited extensions

To enforce limits on allowed extensions use the toggle next to **Globally limit extensions** option. Extensions initially allowed will consist of all currently defined allowed extensions from all existing categories in all workspaces.

<a id="ckbox/latest/features/file-management/workspaces.html--editing-the-list-of-limited-extensions">

#### Editing the list of limited extensions

To edit the list of allowed extensions use the **Edit** button.

<a id="ckbox/latest/features/file-management/workspaces.html--assigning-users-to-workspaces">

### Assigning users to workspaces

Access to workspaces is controlled through the `auth.ckbox.workspaces` field of the [user’s JWT token](#ckbox/latest/guides/configuration/authentication.html--token-payload). As a value, `auth.ckbox.workspaces` takes an array of the workspaces the user should have access to:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "sub": "example-user-id",
    "iat": 1511963669,
    "auth": {
        "ckbox": {
            "role": "superadmin",
            "workspaces": [ "workspace-id-1", "workspace-id-2" ]
        }
    }
}

```

In the above example, the user with ID `example-user-id` is assigned to two workspaces: `workspace-id-1` and `workspace-id-2`.

<a id="ckbox/latest/features/file-management/workspaces.html--multiple-workspaces">

#### Multiple workspaces

If the user is assigned to more than one workspace, he will see a dropdown allowing to change the active workspace:

<a id="ckbox/latest/features/file-management/workspaces.html--access-to-workspaces-for-different-user-roles">

#### Access to workspaces for different user roles

Access to workspaces existing in the [website environment](#ckbox/latest/guides/configuration/authentication.html--website-environment) depends on the user role and works like follows:

* `superadmin` – users with the `superadmin` role set in the token have access to **all the workspaces** that exist in the given website environment. Please note that defining `auth.ckbox.workspaces` for the `superadmin` role has no effect, and it will be ignored.
* `admin`, `user` – user with the `admin` or `user` role has access only to workspaces defined in the `auth.ckbox.workspaces` field (or to the [default workspace](#ckbox/latest/features/file-management/workspaces.html--default-workspace), if no explicit workspaces are defined)

<a id="ckbox/latest/features/file-management/workspaces.html--default-workspace">

#### Default workspace

Each website environment has automatically created a special workspace called the _default workspace_. If access to workspaces is not explicitly set in the user’s JWT token, the user will be automatically assigned to this default workspace.

Please note that if you explicitly define workspaces in the user’s JWT token, the user will not be able to access the default workspace unless its ID is explicitly defined on the list of allowed workspaces in the user’s JWT token defined in `auth.ckbox.workspaces`.

For backward compatibility, the identifier of the _default workspace_ is the same as the identifier of the [website environment](#ckbox/latest/guides/configuration/authentication.html--website-environment).

<a id="ckbox/latest/features/file-management/workspaces.html--usage-examples-of-workspaces">

### Usage examples of workspaces

Below, you will find descriptions of popular use cases where workspaces can be effectively utilized. Please note that the list below is not exhaustive, as workspaces can also be utilized in various customized ways to meet specific requirements when integrating CKBox into your application.

<a id="ckbox/latest/features/file-management/workspaces.html--separate-workspaces-for-users">

#### Separate workspaces for users

An often required scenario in many types of applications is to separate data between different users. For example, you can have a CMS in which you want to provide private file storage to each user. In CKBox, you can create personal space for each user with built-in tools.

This can be achieved with the workspaces feature in two simple steps:

1. Create the workspace – please refer to the [Managing workspaces](#ckbox/latest/features/file-management/workspaces.html--managing-workspaces) section.
2. Assign the user to the workspace by setting the `auth.ckbox.workspaces` field of the user’s JWT token – please refer to the [Assigning users to workspaces](#ckbox/latest/features/file-management/workspaces.html--assigning-users-to-workspaces) section.

All the users sharing the same workspace will have access to the same folders and files within it. To create private user spaces, you must ensure that each user is assigned only to his own workspace.

The complete token payload example in this case can look as follows:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "example-user-id",
    "user": {
        "email": "example@example.com",
        "name": "A User",
        "avatar": "https://example.com/avatars/john.png"
    },
    "auth": {
        "ckbox": {
            "role": "user",
            "workspaces": [ "user-workspace-id" ]
        }
    }
}

```

Please note that users with the `admin` and `user` roles will be limited to the workspace defined in the `auth.ckbox.workspaces` field of the user’s JWT token, while users with the `superadmin` role have access to **all the workspaces** that exist in the current environment. For details, please refer to the [Access to workspaces for different user roles](#ckbox/latest/features/file-management/workspaces.html--access-to-workspaces-for-different-user-roles) section.

<a id="ckbox/latest/features/file-management/workspaces.html--workspaces-for-user-groups">

#### Workspaces for user groups

You can assign any number of users to a workspace. To assign multiple users to a shared workspace with ID `shared-workspace-id`, simply set the workspace ID in `auth.ckbox.workspaces` field of the token issued for chosen users.

The complete token payload example in this case can look as follows:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "example-user-id",
    "user": {
        "email": "example@example.com",
        "name": "A User",
        "avatar": "https://example.com/avatars/john.png"
    },
    "auth": {
        "ckbox": {
            "role": "user",
            "workspaces": [ "shared-workspace-id" ]
        }
    }
}

```

<a id="ckbox/latest/features/file-management/workspaces.html--multi-tenant-applications">

#### Multi-tenant applications

A multi-tenant application is software that serves multiple clients or organizations simultaneously while keeping their data and operations separate and secure. Each tenant typically has its own isolated instance of the application, allowing them to customize their settings and access their own data.

For the purpose of this example let’s consider a multi-tenant CMS system hosting multiple websites, each managed by different groups of users. _Tenant_ is a group of users who share common access with specific privileges to the software instance – in the case of our CMS, each tenant maintains its own website. The website data of each tenant is separated, and we aim to achieve the same data separation in CKBox. Additionally, for each tenant in the considered CMS there are two user groups:

* regular users - content creators
* administrators - users with administrative privileges, allowed to configure website settings

This too can be achieved with the CKBox workspaces feature. In this case, a separate workspace can be created for each tenant, and required users can be assigned to it through setting an appropriate `auth.ckbox.workspaces` property in the payload of the JWT token served to the user from the [token endpoint](#ckbox/latest/guides/configuration/authentication.html--token-endpoint). This way all the users sharing the same workspace will have access to the same folders and files.

In the example CMS system, only administrators are allowed to configure the application, and they will have the `auth.ckbox.role` set to `admin`, granting them access to the [administration panel](#ckbox/latest/features/administration-panel.html) of CKBox.

As described in the [Access to workspaces for different user roles](#ckbox/latest/features/file-management/workspaces.html--access-to-workspaces-for-different-user-roles) section, `admin` and `user` roles in CKBox are associated with the workspace scope, while `superadmin` has access to all the workspaces existing in the current CKBox website environment. In our example CMS, `superadmin` could be the system administrator, who would have access to workspaces of all the tenants existing in the CMS system.

The complete token payload example for the CMS administrator user can look as follows:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "admin-user-id",
    "user": {
        "email": "admin-user@example.com",
        "name": "An Admin User",
        "avatar": "https://example.com/avatars/john.png"
    },
    "auth": {
        "ckbox": {
            "role": "admin",
            "workspaces": [ "tenant-workspace-id" ]
        }
    }
}

```

The complete token payload example for the regular user of the CMS can look as follows:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "regular-user-id",
    "user": {
        "email": "user@example.com",
        "name": "A User",
        "avatar": "https://example.com/avatars/john.png"
    },
    "auth": {
        "ckbox": {
            "role": "user",
            "workspaces": [ "tenant-workspace-id" ]
        }
    }
}

```

<a id="ckbox/latest/features/images/conversion.html">source file: "ckbox/latest/features/images/conversion.html"</a>

## Image conversion

CKBox converts images on the fly during upload and when you fetch images from CKBox on demand.

<a id="ckbox/latest/features/images/conversion.html--format-and-size">

### Format and size

While `webp` is the default format, you can convert image files to all file formats allowed in the CKBox configuration. By default, these include `webp`, `jpeg`, `png`, `gif`, and `tiff`. You can also control the horizontal size of the image.

<a id="ckbox/latest/features/images/conversion.html--example">

#### Example

You can access various optimized image versions by a specifically formatted URL. You can find the base URL in the bottom section of the [asset properties panel](../file-management/assets/metadata.html#metadata).

For example, if the image has a base URL like this:

```
https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/file

```

It will display the full-size 1600px-wide file.

If you need a smaller version in a different size, replace the `file` at the end of the URL with the `images/` slug followed by the horizontal resolution and the file format desired. The URL below will produce a 320 pixels wide `png` file, pictured below.

```
https://ckbox.cloud/huTfIec9s6SodytaMc9x/assets/1aUrKtJqioMR/images/320.png

```

Optimized image:

You can read more about calling optimized images in the [CKBox API reference](https://api.ckbox.io/api/docs#tag/Assets/operation/getImageHandler).

<a id="ckbox/latest/features/images/conversion.html--quality">

### Quality

CKBox controls the quality of uploaded images. Refer to the [Optimization](#ckbox/latest/features/images/optimization.html) guide for more details.

<a id="ckbox/latest/features/images/editing/cropping.html">source file: "ckbox/latest/features/images/editing/cropping.html"</a>

## Cropping images

CKBox offers an extensive set of cropping tools, including many predefined cropping ratios. All cropping tools are available from the side panel.

The crop area marker can be dragged around and its dimensions changed. At the same time, the image can be zoomed in or out, too.

Changes introduced by the CKBox editing tools are incremental. It means that after cropping an image, you can either use the **Apply** button in the top bar and [save the image](#ckbox/latest/features/images/editing/editing.html--saving-changes) or keep on adding other changes, like [rotation or mirror](#ckbox/latest/features/images/editing/rotating-flipping.html).

<a id="ckbox/latest/features/images/editing/cropping.html--aspect-ratio-crops">

### Aspect ratio crops

The topmost section of the side panel offers several presets with a fixed aspect ratio, fit for variety of applications.

* **Freeform** – the only preset without a fixed aspect ratio, allows the user to simply drag the crop handles as needed to choose the desired image area size and shape. The crop cannot be larger than the original image, i.e. CKBox will not upscale the picture.
* **Original** – a fixed crop area with the aspect ratio the same as the original image. Only the size of the crop area can be changed.
* **1:1**, **4:3**, **16:9**, **3:4**, **9:16** – several predefined aspect ratios based on popular screen resolutions originating from movies, tv, and mobile. Again, only the size of the crop area can be changed.

<a id="ckbox/latest/features/images/editing/cropping.html--dimensions">

### Dimensions

The dimensions input field in the middle of the side panel serves a double purpose. First of all, it is the indicator of the current crop area dimensions. You can observe the numbers displayed there change accordingly as the crop area size is changed in the screencast at the beginning of this guide.

The dimensions input field can also be used to manually enter the desired crop area. If the size ratio padlock is ticked, it is enough to introduce just the width or the height, as the other dimension will be calculated automatically. You can also unlock the aspect ratio by choosing the **Freeform** setting to enter both dimensions as desired.

<a id="ckbox/latest/features/images/editing/cropping.html--presets">

### Presets

The last cropping tool is the social network presets dropdown. The preset dropdown acts similarly to the aspect ratio presets. However, instead of screen resolutions, it offers sets of predefined dimensions for the most popular social networks. These include sets designed specifically for Facebook, Instagram, Twitter, and LinkedIn.

No matter what the size of the preview is, the effective cropped image dimensions will be as stated in the preset. It means the actual crop for a Facebook profile will always end up as a 70x70px square, while a LinkedIn cover will always be 1128x191px. This means that the original image will be scaled down or **upscaled** if needed. Please note, that in the case of small images, this may result in poorer quality than the original.

<a id="ckbox/latest/features/images/editing/editing.html">source file: "ckbox/latest/features/images/editing/editing.html"</a>

## Editing images in CKBox

CKBox provides image editing tools like cropping, resizing, or rotating. Utilizing these tools on the go, straight from the asset manager, makes working on content faster and more efficient. It saves time and resources as there is no need to resort to using a dedicated image editing software.

<a id="ckbox/latest/features/images/editing/editing.html--using-the-editing-tools">

### Using the editing tools

To edit an image, use the **Edit** button on the top bar. The button might be hidden under a three-dot dropdown menu on narrow viewports.

<a id="ckbox/latest/features/images/editing/editing.html--main-editing-screen">

### Main editing screen

Upon opening the file for editing, the user will have access to most editing tools thanks to a clear, modern interface of the editing area. The image is displayed in the central part of the editing area. You may drag it around the editing area with a mouse click.

<a id="ckbox/latest/features/images/editing/editing.html--top-bar">

#### Top bar

The top bar shows the **exit arrow** in the top left corner. Pressing it will leave the editing tool and discard all changes made so far. Pressing Escape will have the same effect.

Next is the image file name.

The **Reset button** will discard all changes made without exiting the tool.

The **Apply** button will apply all changes to the image and open the [save dialog](#ckbox/latest/features/images/editing/editing.html--saving-changes).

<a id="ckbox/latest/features/images/editing/editing.html--floating-toolbar">

#### Floating toolbar

The floating toolbar at the bottom provides the following tools and information (from left):

* The rotate and flip (mirror) tools – see the [Rotation and flipping](#ckbox/latest/features/images/editing/rotating-flipping.html) guide.
* **Final** image dimensions – these are the effective dimensions of the image after all operations are applied.
* Zoom controls – the user may zoom and out the image as desired. You may also use the **mouse scrolling wheel** to zoom in and zoom out on an image.

<a id="ckbox/latest/features/images/editing/editing.html--side-panel">

#### Side panel

The top part of the side panel provides numerous cropping-related tools. Refer to the [Cropping](#ckbox/latest/features/images/editing/cropping.html) guide for more details on how to use these.

The lower part of the side panel repeats the rotating and flipping (mirroring) tools you can read more about in the [Rotating and flipping](#ckbox/latest/features/images/editing/rotating-flipping.html) guide.

The bottom part shows current file information, such as file upload and last modification date, file size, and **original** dimensions (before applying crop, flip, or resize operations).

<a id="ckbox/latest/features/images/editing/editing.html--saving-changes">

### Saving changes

Upon clicking the **Apply** button in the top bar, the save dialog will appear. It shows the current version of the image (with the crop, rotate, or flip operations applied).

The **Image options** section allows for changing the file name and saving the edited file as a new asset in CKBox.

Ticking the **Overwrite file** checkbox will make the asset manager apply changes to the original image file.

The **Image resize** section shows the effective dimensions of the saved image. It also allows for [resizing images](#ckbox/latest/features/images/editing/resize.html).

<a id="ckbox/latest/features/images/editing/editing.html--applying-multiple-changes">

### Applying multiple changes

Changes introduced by the CKBox editing tools are incremental. It means that after applying a mirror flip or cropping an image, you can keep on adding other changes, like rotation. The preview area will show all changes. These will only be committed after pressing the **Apply** button on the top bar.

<a id="ckbox/latest/features/images/editing/editing.html--output-quality">

#### Output quality

The CKBox editing tools work on the server side and do not physically commit changes to the file before the user hits the **Apply** button. Thanks to that, the image files are not processed applying changes, ensuring the best possible outcome in terms of file compression and image quality.

<a id="ckbox/latest/features/images/editing/resize.html">source file: "ckbox/latest/features/images/editing/resize.html"</a>

## Resizing images in CKBox

To resize an image, you need to get to the save dialog. To do this, first, click the **Apply** button located on the right in the top bar of the image editing area.

The save dialog will appear.

Use the **Image resize** tool in the save dialog to change the file dimensions. Change the width or height of the image to the desired value. The other dimension will be calculated automatically.

The size ratio is fixed for this operation. If you wish to resize the image without a fixed size ratio, please refer to the [Cropping](#ckbox/latest/features/images/editing/cropping.html) guide.

Click **Save** to finalize the operation. You can overwrite the original file or rename it and save as a new one.

<a id="ckbox/latest/features/images/editing/rotating-flipping.html">source file: "ckbox/latest/features/images/editing/rotating-flipping.html"</a>

## Rotating and flipping

The rotate and flip (mirror) tools are available both from the floating toolbar available at the bottom of the image editing area as well as in the lower portion of the side panel.

Changes introduced by the CKBox editing tools are incremental. It means that after applying a flip or a rotation, you can either use the **Apply** button in the top bar and [save the image](#ckbox/latest/features/images/editing/editing.html--saving-changes) or keep on adding other changes, like [cropping](#ckbox/latest/features/images/editing/cropping.html).

<a id="ckbox/latest/features/images/editing/rotating-flipping.html--rotating-images">

### Rotating images

The rotate tool can be used to change the image’s orientation both clockwise and counterclockwise by steps of 90°. At present, rotating an image at an arbitrary angle is not available.

To rotate the image, use the rotation buttons located both at the floating toolbar and the side panel.

<a id="ckbox/latest/features/images/editing/rotating-flipping.html--flipping-mirroring-images">

### Flipping (mirroring) images

CKBox lets you mirror – flip the image both horizontally (upside-down) and vertically (left-right).

To flip the image, use the mirroring buttons located both at the floating toolbar and the side panel.

<a id="ckbox/latest/features/images/optimization.html">source file: "ckbox/latest/features/images/optimization.html"</a>

## Image optimization

The `webp` format is an image format optimized to use on the web. This kind of image allows for substantial savings in the amount of data sent by the browser.

<a id="ckbox/latest/features/images/optimization.html--image-optimization-levels">

### Image optimization levels

CKBox administrators may fine-tune the quality of the rescaled versions of images produced by the file manager. Five predefined quality settings are available to adjust the compression to your needs.

You can read more about it in the [Image management](#ckbox/latest/features/administration-panel.html--image-management) section of the Administration panel guide.

<a id="ckbox/latest/features/images/optimization.html--using-optimized-image-versions">

### Using optimized image versions

You can access an image directly via the image URL found in the bottom section of the [asset properties panel](../file-management/assets/metadata.html#metadata). You can display optimized image versions using this URL, as described in the [Image conversion](#ckbox/latest/features/images/conversion.html--format-and-size) guide.

<a id="ckbox/latest/features/images/optimization.html--benefits-of-using-the-webp-format">

### Benefits of using the `webp` format

The `webp` format provides substantial savings compared to traditional formats. For example, the table below shows data amount savings compared to the lossy `jpg` format.

| **File format** | **Savings**    |
| --------------- | -------------- |
| .jpg            | full size      |
| lossless .webp  | 26% smaller    |
| lossy .webp     | 25-34% smaller |

In CKBox, the `webp` format is a first-class citizen.

All uploaded images are **kept in the original format**, but the CKBox backend service automatically produces their `webp` version. The `webp` file is then used wherever possible to speed up your web pages, but also internally by CKBox — for example, to display thumbnails.

Some older browsers may not support `webp`, but CKBox covers these cases too. The markup for responsive images contains a graceful fallback to the original format, so the image will always be displayed properly, even in older browsers.

There is one more benefit of using `webp`: smaller, optimized images that load faster will boost the SEO of your web pages.

Additionally, `webp` supports both **transparency** and **animations**, so it can effectively replace **any other image format**.

<a id="ckbox/latest/features/images/overview.html">source file: "ckbox/latest/features/images/overview.html"</a>

## Images

CKBox is an advanced, versatile file manager. It is also a great tool for managing images. It can act as a native image uploader for WYSIWYG editors such as CKEditor 5, but not only. CKBox offers image optimization, and conversion and supports responsive images. It also provides useful editing tools.

<a id="ckbox/latest/features/images/overview.html--wide-range-of-supported-image-formats">

### Wide range of supported image formats

CKBox supports several most popular image file types, including the `webp`, `jpeg`, `png`, `gif`, and `tiff` formats. The set provides images fit for most applications, including online content where compression and size are the most important as well as formats that put image quality in the first place. The original uploaded image file is kept as an asset, which can be called by the user in any of the supported formats.

<a id="ckbox/latest/features/images/overview.html--image-optimization-and-responsive-images">

### Image optimization and responsive images

Preserving the best quality and the lowest file size thanks to [advanced optimization](#ckbox/latest/features/images/optimization.html) positively impacts the website’s loading time and SEO performance. The CKBox service also supports creating several versions of an image to address the needs of [responsive web design](#ckbox/latest/features/images/responsive-images.html). Any of these optimized versions can be displayed automatically, based on the output viewport, or accessed directly by the user.

<a id="ckbox/latest/features/images/overview.html--format-conversion">

### Format conversion

The `webp` image format, which provides superior lossless and lossy compression for images on the web, is the default output. However, CKBox offers [two-way conversion](#ckbox/latest/features/images/conversion.html) between all supported formats.

<a id="ckbox/latest/features/images/overview.html--image-editing-tools">

### Image editing tools

The service also provides [image editing](#ckbox/latest/features/images/editing/editing.html) capabilities to make working with assets faster and more efficient.

<a id="ckbox/latest/features/images/responsive-images.html">source file: "ckbox/latest/features/images/responsive-images.html"</a>

## Responsive images

Responsive images automatically adjust their size and resolution based on the device or screen size they are being viewed on. This brings faster loading times, improved website performance, and better user experience, ultimately reducing bandwidth usage and enhancing page responsiveness.

When you embed an image in CKEditor 5 using CKBox, it will produce a `<picture>` element containing several images optimized for the given breakpoint in the outcome HTML code.

<a id="ckbox/latest/features/images/responsive-images.html--how-it-works">

### How it works

Upon uploading a file, CKBox will store the original asset. Then, responding to calls (for example, from the [CKEditor 5 plugin](#ckeditor5/latest/features/file-management/ckbox.html)), it will create several intermediate versions. The number of these intermediate versions and their resolutions depend on the resolution of the original image. The larger the original image is, the more versions will be created — up to ten for the biggest assets.

<a id="ckbox/latest/features/images/responsive-images.html--breakpoints">

### Breakpoints

The first breakpoint for creating an optimized version should equal 10% of the image width but no less than 80 pixels. Each subsequent version will be twice the size of the previous one until the original size is reached.

<a id="ckbox/latest/features/images/responsive-images.html--example">

#### Example

An image with a width of 700px will have the smallest version set to 80px wide as the 10% width is too small. The larger versions will be calculated based on this. It means the next ones will be: 160px, 240px, 320px, and 640px.

Similarly, the first breakpoint step for a 1600px wide image is 160px. The next ones are 320px, 480px, 640px, and 1280px.

There is no upscaling — CKBox will only produce intermediate images smaller than the original one.

<a id="ckbox/latest/features/images/responsive-images.html--outcome">

### Outcome

The browser will automatically load the image with dimensions most suitable for the presented page resolution, which makes the image load much faster. Bigger images are suitable for desktop users, so image details are visible. Using the same image on a mobile device with a smaller screen resolution would be a waste of bandwidth — a smaller image loads faster, improving the experience of your visitors.

You can observe [responsive images in action](#ckeditor5/latest/features/images/images-responsive.html) in the CKEditor 5 documentation.

<a id="ckbox/latest/features/index.html">source file: "ckbox/latest/features/index.html"</a>

## CKBox features

CKBox is a dedicated asset manager supporting file and image uploads. It provides image conversion and optimization on the fly and provides a responsive images mechanism for the CKEditor 5 plugin. It also offers image editing capabilities to make working with assets faster and more efficient.

Find out about CKBox’s various features.

* [Managing assets](#ckbox/latest/features/file-management/overview.html) – Uploading, moving, describing, and categorizing your files.
* [Handling images](#ckbox/latest/features/images/overview.html) – How images are served and handled in CKBox.
* [Editinging images](#ckbox/latest/features/images/editing/editing.html) – Using the CKBox image editing tools.
* [Administration panel](#ckbox/latest/features/administration-panel.html) – Configuring CKBox instance.
* [Permissions](#ckbox/latest/features/permissions.html) – Managing security and controlling access.
* [Private Categories](#ckbox/latest/features/private-categories.html) – Protecting resources in CKBox.
* [REST API](#ckbox/latest/features/rest-api.html) – Utilizing the REST API service.

**See also**

* [Getting started with CKBox](#ckbox/latest/guides/index.html) – Setting up your copy of CKBox, configuring it, and integrating it
* [Examples](#ckbox/latest/examples/index.html) – Check out various implementations and customizations
* [Support](#ckbox/latest/support/index.html) – Getting help

<a id="ckbox/latest/features/permissions.html">source file: "ckbox/latest/features/permissions.html"</a>

## Permissions

Permissions enable fine-grained control over user access to specific features and actions. By assigning permissions, admins can restrict user access to selected resources and their interactions with assets, categories, and folders.

Users are assigned to groups with sets of permissions assigned.

Depending on the user’s permissions, UI elements may be hidden. For example, if the user does not have permission to create an asset the upload button will not be available to us and the drag and drop area will be disabled. Similarly, if the group to which the user is assigned does not have permission to delete folders, the `Delete` button will not be available and the Del shortcut will not be active either.

<a id="ckbox/latest/features/permissions.html--permissions-structure">

### Permissions structure

Groups serve as an organizational unit for managing user access and permissions. User groups allow administrators to assign permissions to multiple users at once. Admins and Superadmins can create groups. Users are assigned to a particular group or groups via JWT. Each group can be assigned to a specific permissions set and category.

A default group is a special group that exists in each workspace. It serves as a fallback in the absence of a group defined in JWT. It is created together with the workspace and is not removable. By default, it has all permissions, but this can be changed manually.

Permissions introduce control over the following actions:

* **Accessing a Category:** Allows users to view the contents of a specific category. Users with this permission can browse and access assets stored within the designated category. Without this permission, the category will not be listed. Access to this category by its ID without permission would result in a `403` status error.
* **Creating an Asset:** Grants users the ability to upload new assets, and copy existing assets to a particular category.
* **Deleting an Asset:** Enables users to delete assets from the category or a folder.
* **Modifying an Asset:** Allows users to edit and make changes to existing assets. Users with this permission can update assets by overwriting their content (both using the REST API and image editor with the `Overwrite` option).
* **Modifying Asset Metadata:** Provides users with the capability to edit and update metadata associated with assets. Metadata includes information such as titles, descriptions, and tags, but **not the content**.
* **Creating a Folder:** Grants users the privilege to create new folders. This also includes creating a folder via the `Folder upload` feature.
* **Modifying a Folder Metadata:** Enables users to edit and update metadata associated with folders (`name`).
* **Deleting a Folder:** Allows users to delete folders.

<a id="ckbox/latest/features/permissions.html--creating-user-groups">

### Creating user groups

To create a new group, go to the “Settings” section of the CKBox administration panel. There, choose the “Permissions” tab. Use the + button to add a new group.

Type the desired group name in the pop-up dialog. Hit “Save” to confirm the creation of a new group.

The newly-made user group is now accessible from the groups listing in the “Permissions” tab.

An ID is displayed below the group name. It will be later needed to assign users to groups. Adding permissions sets can be done via the “Manage permissions” option.

<a id="ckbox/latest/features/permissions.html--managing-permissions">

### Managing permissions

To assign a set of permissions to a new group, hit the “Manage permissions” button, right to the group you want to add the permissions to. Then, use the + button to add a new permission rule.

From the list, select the permissions you want to enable, using the toggle switches.

If desired, select specific categories the new permission rule should apply to with the toggle switch. If left off, it will apply to all CKBox categories.

Hit “Save” when done with setting permissions.

<a id="ckbox/latest/features/permissions.html--assigning-users-to-groups">

### Assigning users to groups

Users can be assigned to groups in JWT in the `auth.ckbox.groups` configuration option. Groups must be listed as IDs. These can be found in the user groups listing in the Permissions management pane in the Setting console. Group ID is displayed below the group name, as shown below.

Below you can see a sample user assigned to two groups.

```
{
    "aud": "62476038ee047dca1a0b",
    "sub": "RamlmkVZBgG6BW2DeUi4d",
    "auth": {
        "ckbox": {
            "role": "user",
            "groups": ["d85fe574fd2a", "kCIUkF4iUPRj"]
        }
    },
    "iat": 1721311797,
    "exp": 1721315397
}

```

Permissions are only checked for regular users. Admins and superadmins have all access granted by default.

<a id="ckbox/latest/features/permissions.html--handling-clashing-permissions">

### Handling clashing permissions

In scenarios where a user is assigned to multiple groups with different permissions, such as being a member of both the Marketing Team with access to the Videos category and the Sales Team with access to the Documents category, the principle of clashing permissions comes into play. When permissions clash, CKBox defaults to an “Allow” resolution. This means the user’s effective permissions are the union of all their group assignments.

For example, suppose a user is part of the “Marketing Team” which allows access to the “Videos” category, and the “Sales Team” which allows access to the “Documents” category. In that case, the user will have access to both the “Videos” and “Documents” categories. This ensures that users have the broadest access possible based on their group memberships.

Additionally, if the “Marketing Team” has permission to create and modify assets while the “Sales Team” has permission to delete assets, the user will inherit both these permissions. The user will be able to create, modify, and delete assets within the categories they have access to. This approach simplifies permission management by ensuring that users do not encounter unexpected access denials due to overlapping group permissions.

As a result, users can perform any action permitted by any of their assigned groups. This mechanism is crucial in collaborative environments where users might need to access and interact with a wide range of resources to perform their roles effectively.

<a id="ckbox/latest/features/private-categories.html">source file: "ckbox/latest/features/private-categories.html"</a>

## Private Categories

The “Private Categories” feature allows administrators to mark specific categories as “Private.” If a category is set to private, all assets in that category or any of its subfolders are protected.

Categories marked as “Private” will require special authorization to view or download the assets within them.

CKBox automatically handles the authorization process for the assets via its UI.

<a id="ckbox/latest/features/private-categories.html--making-a-category-private">

### Making a category private

1. To make a category private, go to the “Settings” section of the CKBox administration panel.
2. Choose the “Asset categories” tab.
1. Click on the “Edit” button for the category you want to make private.
2. Select the `Make this category private` checkbox, then save.
1. Private categories are marked `Private` on the categories list

<a id="ckbox/latest/features/private-categories.html--authorization-process">

### Authorization process

To access assets in private categories, users must obtain an authorization cookie by making an API request to the `/authorize` endpoint using a valid JWT from the token endpoint.  
The cookies used for authorization are partitioned cookies using CHIPS (Cookies Having Independent Partitioned State). They ensure secure and scoped access to protected resources.

Once authorized, users with the proper permissions will be able to preview or download assets.

**Steps to obtain authorization cookie:**

1. Send a GET request to the `/authorize` endpoint with the JWT in the `Authorization` header.
2. Ensure `credentials: include` is used in the fetch request to allow the browser to handle any `Set-Cookie` headers returned by the server.
3. If the JWT is valid, the response will set a cookie (`CKBox-Auth` or `__Host-CKBox-Auth`) in the browser, which will then be used for subsequent requests to access protected resources.

```
const formData = new FormData();
formData.append('token', {{JWT}});

fetch('https://{{CKBOX_API}}/categories/authorizePrivateAccess', {
  method: 'POST',
  mode: 'no-cors',
  body: formData
  credentials: 'include'  // Ensures cookies are handled
})
.then(response => {
  if (!response.ok) {
    throw new Error('Authorization failed');
  }
});

```

<a id="ckbox/latest/features/private-categories.html--access-control-flow">

### Access control flow

1. Users first obtain a JWT via a Token endpoint.
2. The user makes a request to `/authorize` to receive the authorization cookie. The browser attaches the cookie to all subsequent API calls related to fetching asset’s content.
3. The system checks the user’s permissions to ensure they have access to the private category.
4. With both the authorization cookie and valid permissions, users can access and download assets.

<a id="ckbox/latest/features/private-categories.html--example-use-case-cms-with-sensitive-embedded-content">

### Example use-case: CMS with sensitive embedded content

Having a CMS handling sensitive information that includes embedded content such as images or documents. To ensure this sensitive data is protected, an administrator can mark certain categories containing these assets as “Private.” This means that all assets embedded within the CMS content will require proper authorization to be accessed.

In this scenario:

* Only users with valid sessions in the CMS can access the embedded assets, by doing preauthorization using `GET:/authorize` endpoint.
* The `/authorize` call can be made immediately after the user logs in, ensuring that sensitive content is visible to authorized users. When the user logs out, the authorization cookie can be purged, revoking access.
* If an attempt is made to access the content outside the CMS without proper authorization, CKBox will return a 401 Unauthorized error.

<a id="ckbox/latest/features/rest-api.html">source file: "ckbox/latest/features/rest-api.html"</a>

## CKBox REST API

CKBox offers a [REST API](https://api.ckbox.io/api/docs) for more convenient integration with your application and workflow automation. It is useful for migration from another digital asset manager, mass upload or modification of assets and their metadata, or when you want to interact with your assets without using the UI.

With the REST API, you can:

* Upload and manage assets in CKBox.
* Download assets.
* Manage your folders.
* Create asset categories and change their configuration.
* Move and copy assets between folders.
* Resize images and automatically convert them to any of the supported formats (`webp`, `jpeg`, `png`, `gif`, `tiff`).
* Control the quality of images produced by CKBox.
* Fetch the list of recently used assets for a given user.
* Fetch and modify asset metadata, such as the tags, description, name, or any custom attributes.
* Search within your assets.

Refer to the [CKBox REST API documentation](https://api.ckbox.io/api/docs) to read about the available REST API endpoints.

<a id="ckbox/latest/features/rest-api.html--connecting-to-the-rest-api">

### Connecting to the REST API

<a id="ckbox/latest/features/rest-api.html--authentication">

#### Authentication

Authentication for requests to the CKBox REST API requires a JWT token. This token must be included in the `Authorization` header of the requests.

To create a JWT token for authentication, use the same algorithm like for tokens that authenticate your users in CKBox. Refer to the [Authentication](#ckbox/latest/guides/configuration/authentication.html) guide for more information about tokens, available fields, and examples of algorithms that produce JWT tokens.

In the CKBox REST API, some endpoints require the `admin` user role to be present in the token. To use all available endpoints when communicating with the API, you should use tokens with `auth.ckbox.role` set to `admin` in the token payload.

Here is an example of the token payload required to authenticate requests sent to the CKBox REST API that grants access to all endpoints, including those that perform actions of the administrator user:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "sub": "example-user-id",
    "iat": 1511963669,
    "auth": {
        "ckbox": {
            "role": "admin"
        }
    }
}

```

<a id="ckbox/latest/features/rest-api.html--payload-properties">

#### Payload properties

You **must** include the following properties in the JWT token payload:

* `aud` – The environment ID. This is the identifier of the environment created in the [Customer Portal](https://portal.ckeditor.com).
* `sub` – The user ID. This is the unique identifier of the user for whom the token is issued.
* `iat` – A timestamp the token was **issued at**. Ensure that `iat` is present and contains the correct time given in seconds. Some JWT implementations do not include it by default. The system time may also be invalid, causing strange issues with tokens (see, for example, [Docker for Mac time drift](https://github.com/docker/for-mac/issues/2076)).
* `auth` – An object defining the user’s role. Allowed values are `user` for regular users and `admin` for administrator users.

<a id="ckbox/latest/features/rest-api.html--sending-request">

### Sending request

To interact with the CKBox service, send all the requests to the https://api.ckbox.io/ domain. Additionally, the token payload includes information about your environment ID carried in the `aud` field. It enables the CKBox service to recognize requests intended for your specific CKBox environment.

In this example, let’s assume you want to fetch a list of all asset categories available in your CKBox instance. To obtain this information, you can use the [GET /categories](https://api.ckbox.io/api/docs#tag/Categories/operation/getCategories) endpoint. Assuming that you have already created a valid JWT token to authenticate the request, your request should look like the following:

```
curl 'https://api.ckbox.io/categories' -H 'Authorization: <jwt_token>'

```

Replace the `<jwt_token>` placeholder with your JWT token and send the request to the CKBox API endpoint. It should return a JSON containing the list of asset categories from your CKBox environment.

<a id="ckbox/latest/features/rest-api.html--example-application">

### Example application

Below you can find a complete code of an example for Node.js. The code signs a JWT token with the required payload and then sends the request to the CKBox REST API to obtain the list of asset categories.

Before you run this code, replace <environment\_id> and <access\_key> with the environment ID and access key obtained in the [Customer Portal](https://portal.ckeditor.com).

```
const jwt = require('jsonwebtoken');
const axios = require('axios');

const ENVIRONMENT_ID = '<your_environment_id>'; // Provide your environment ID.
const ACCESS_KEY = '<your_access_key>';         // Provide your access key.

const getToken = (userId, role) => {
    return jwt.sign(
        {
            aud: ENVIRONMENT_ID,
            sub: userId,
            auth: {
                ckbox: {
                    role
                }
            }
        },
        ACCESS_KEY,
        {
            algorithm: 'HS256'
        }
    );
};

axios.get('https://api.ckbox.io/categories', {
        headers: {
            Authorization: getToken('dummy-admin-id', 'admin')
        }
    })
    .then(response => console.dir(response.data, { depth: 5 }))
    .catch(error => console.error(error.response.data));

```

For a complete working example, refer to the [CKBox Code Examples repository](https://github.com/ckbox-io/ckbox-examples/tree/main/rest-api).

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html">source file: "ckbox/latest/features/sdk/backend-sdk/assets-management.html"</a>

## Assets Management Guide

The CKBox Node.js SDK provides comprehensive asset management capabilities that allow you to retrieve, organize, and manage your uploaded files. This guide covers all aspects of asset management, from basic retrieval to advanced filtering and bulk operations.

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--asset-management-overview">

### Asset Management Overview

The `assets` component of the CKBox SDK provides the following main operations:

| Method                                                                                                        | Purpose                                     | Return Type    |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -------------- |
| [getAsset(id)](#ckbox/latest/features/sdk/backend-sdk/assets-management.html--getting-a-single-asset)         | Retrieve a single asset by ID               | CKBoxAsset     |
| [getAssets(options)](#ckbox/latest/features/sdk/backend-sdk/assets-management.html--basic-asset-listing)      | List assets with filtering and pagination   | CKBoxAssetList |
| [softDeleteAssets(ids)](#ckbox/latest/features/sdk/backend-sdk/assets-management.html--soft-delete-assets)    | Soft delete multiple assets (move to trash) | void           |
| [deleteAssets(ids)](#ckbox/latest/features/sdk/backend-sdk/assets-management.html--permanently-delete-assets) | Permanently delete multiple assets          | void           |

All methods support workspace isolation and respect user permissions based on the configured role.

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--basic-asset-retrieval">

### Basic Asset Retrieval

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--getting-a-single-asset">

#### Getting a Single Asset

Retrieve a specific asset using its unique ID to access detailed information about the file.

```
import CKBox from '@ckbox/sdk-node';

const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

async function getAssetById(assetId) {
  try {
    const asset = await ckbox.assets.getAsset(assetId);
    
    console.log('Asset Details:');
    console.log('- Name:', asset.name);
    console.log('- Size (B):', asset.size);
    console.log('- URL:', asset.url);
    console.log('- Category:', asset.categoryId);
    console.log('- Last Modified:', new Date(asset.lastModifiedAt).toLocaleString());
    
    return asset;
  } catch (error) {
    console.error('Failed to retrieve asset:', error.message);
    throw error;
  }
}

// Usage
const asset = await getAssetById('asset_12345');

```

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--listing-assets-with-pagination">

### Listing Assets with Pagination

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--basic-asset-listing">

#### Basic Asset Listing

Retrieve a paginated list of assets with filtering and sorting options to manage large collections efficiently.

```
async function listAssets() {
  try {
    const assetList = await ckbox.assets.getAssets({
      categoryId: {{categoryId}},
      limit: 20,
      offset: 0,
      sortBy: 'uploadedAt',
      order: 'desc'
    });
    
    console.log(`Found ${assetList.totalCount} assets`);
    console.log(`Showing ${assetList.items.length} assets (offset: ${assetList.offset})`);
    
    assetList.items.forEach((asset, index) => {
      console.log(`${index + 1}. ${asset.name} (${asset.size})`);
    });
    
    return assetList;
  } catch (error) {
    console.error('Failed to list assets:', error.message);
    throw error;
  }
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--asset-operations">

### Asset Operations

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--soft-delete-assets">

#### Soft Delete Assets

Move multiple assets to trash (soft delete) - assets can be restored later:

```
async function softDeleteAssets(assetIds) {
  try {
    console.log(`Moving ${assetIds.length} assets to trash...`);
    
    // Soft delete the assets (move to trash)
    await ckbox.assets.softDeleteAssets(assetIds);
    
    console.log(`✅ ${assetIds.length} assets moved to trash successfully`);
    return true;
  } catch (error) {
    console.error(`❌ Failed to move assets to trash:`, error.message);
    throw error;
  }
}

// Usage
const assetIds = ['asset_1', 'asset_2', 'asset_3'];
await softDeleteAssets(assetIds);

```

<a id="ckbox/latest/features/sdk/backend-sdk/assets-management.html--permanently-delete-assets">

#### Permanently Delete Assets

Permanently remove multiple assets from CKBox (cannot be restored):

```
async function permanentlyDeleteAssets(assetIds) {
  try {
    console.log(`Permanently deleting ${assetIds.length} assets...`);
    
    // Permanently delete the assets
    await ckbox.assets.deleteAssets(assetIds);
    
    console.log(`✅ ${assetIds.length} assets permanently deleted`);
    return true;
  } catch (error) {
    console.error(`❌ Failed to permanently delete assets:`, error.message);
    throw error;
  }
}

// Usage - be careful, this cannot be undone!
const assetIds = ['asset_1', 'asset_2', 'asset_3'];
await permanentlyDeleteAssets(assetIds);

```

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html">source file: "ckbox/latest/features/sdk/backend-sdk/configuration-options.html"</a>

## Configuration Options

The CKBox Node.js SDK provides a flexible configuration system that allows you to customize the SDK behavior to match your application’s requirements. This guide covers all available configuration options, their purposes, and usage examples.

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--required-properties">

### Required Properties

| Property      | Type   | Description                                                                                          |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| accessKey     | string | The access key obtained from the Customer Portal                                                     |
| environmentId | string | The environment identifier that specifies which CKBox environment your application should connect to |

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--optional-properties">

### Optional Properties

| Property      | Type   | Description                             |
| ------------- | ------ | --------------------------------------- |
| workspaceId   | string | Workspace context for the user session  |
| role          | string | Permission level for the user session   |
| userId        | string | Unique identifier for the user          |
| userName      | string | Human-readable name for the user        |
| serviceOrigin | string | Sets the origin to use for the REST API |

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--property-details">

### Property Details

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--accesskey">

#### `accessKey`

**Type:** `string`  
**Required:** Yes

The access key obtained from the Customer Portal. This key is used to authenticate your application with CKBox services.

```
const ckbox = new CKBox({
  accessKey: 'your-secret-access-key',
  // ... other options
});

```

**Important Security Notes:**

* Never expose this key in client-side code
* Store it as an environment variable
* Rotate keys regularly for enhanced security

**Example with environment variable:**

```
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--environmentid">

#### `environmentId`

**Type:** `string`  
**Required:** Yes

The environment identifier that specifies which CKBox environment your application should connect to. Environments allow you to separate different stages of your application (development, staging, production).

```
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: 'env_123456789',
});

```

**How to find your Environment ID:**

1. Log in to the Customer Portal
2. Navigate to “Subscription” -> “Cloud Environments”
3. Copy the ID from your desired environment

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--workspaceid">

#### `workspaceId`

**Type:** `string`  
**Required:** No

Specifies the workspace context for the user session. Workspaces provide data isolation in multi-tenant applications.

```
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  workspaceId: 'workspace_user_123'
});

```

**Fallback behavior:**

* If not provided, operations will use the default workspace for the environment

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--role">

#### `role`

**Type:** `string`  
**Required:** No

Defines the permission level for the user session. Controls what operations the user can perform.

**Available roles:**

* `'user'` (default) - Basic role
* `'admin'` \- Administrative permissions including category management
* `'superadmin'` \- Full system permissions

```
// User with basic permissions
const userCkbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  role: 'user'
});

// Admin with extended permissions
const adminCkbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  role: 'admin'
});

```

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--userid">

#### `userId`

**Type:** `string`  
**Required:** No

A unique identifier for the user. This is used for tracking, auditing.

```
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  userId: 'user_12345',
  userName: 'John Doe'
});

```

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--username">

#### `userName`

**Type:** `string`  
**Required:** No

A human-readable name for the user.

```
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  userId: 'user_12345',
  userName: 'John Doe'
});

```

<a id="ckbox/latest/features/sdk/backend-sdk/configuration-options.html--serviceorigin">

#### `serviceOrigin`

**Type:** `string`  
**Required:** No

The base URL for the CKBox API service. This allows you to use custom API endpoints or different service regions. **This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.**

```
// Using default service
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
  // serviceOrigin defaults to 'https://api.ckbox.io'
});

// Using custom endpoint
const customCkbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  serviceOrigin: 'https://{{self-hosted-ckbox}}.com'
});

```

**Default value:** `https://api.ckbox.io`

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html">source file: "ckbox/latest/features/sdk/backend-sdk/file-upload.html"</a>

## File Upload Guide

The CKBox Node.js SDK provides file upload capabilities with support for multiple upload methods, categorization, progress tracking, and concurrent upload management.

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-methods-overview">

### Upload Methods Overview

The SDK offers three primary upload methods:

| Method                                                                                        | Use Case              | Input Type           |
| --------------------------------------------------------------------------------------------- | --------------------- | -------------------- |
| [uploadFile()](#ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-from-file)     | Upload from file path | File system path     |
| [uploadBuffer()](#ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-from-buffer) | Upload from memory    | Buffer object        |
| [uploadStream()](#ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-file-stream) | Upload from stream    | ReadStream or Buffer |

All methods support:

* **Progress tracking** with real-time callbacks
* **Categorization** and folder organization
* **Concurrent uploads** with automatic queue management
* **Error handling** with detailed error information

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--basic-upload-examples">

### Basic Upload Examples

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-from-file">

#### Upload from File

The simplest way to upload a file is using `uploadFile()` with a file system path.

```
import CKBox from '@ckbox/sdk-node';

const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

// Basic file upload
async function uploadImage() {
  try {
    const result = await ckbox.uploader.uploadFile('./images/photo.jpg');
    
    console.log('Upload successful!');
    console.log('Asset ID:', result.id);
    console.log('File URL:', result.url);
    console.log('File size:', result.size);
    
    return result;
  } catch (error) {
    console.error('Upload failed:', error.message);
    throw error;
  }
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-from-buffer">

#### Upload from Buffer

Upload files that are already in memory as Buffer objects, useful for dynamically generated content.

```
import fs from 'fs';

async function uploadFromBuffer() {
  // Read file into buffer
  const fileBuffer = fs.readFileSync('./image.png');
  
  const result = await ckbox.uploader.uploadBuffer(
    fileBuffer,
    'my-image.png'
  );
  
  console.log('Buffer uploaded successfully:', result.id);
  return result;
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-file-stream">

#### Upload File Stream

Use streams for memory-efficient uploads of large files, especially useful when processing large media files.

```
import fs from 'fs';

async function uploadFileStream() {
  const filePath = './large-video.mp4';
  const stream = fs.createReadStream(filePath);
  
  const result = await ckbox.uploader.uploadStream(
    stream,
    'large-video.mp4'
  );
  
  console.log('Stream upload completed:', result.id);
  return result;
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-to-specific-category">

#### Upload to specific category

Organize uploads by assigning them to predefined categories to help structure your file organization.

```
async function uploadToCategory() {
  const result = await ckbox.uploader.uploadFile('./document.pdf', {
    categoryId: '{{categoryId}}'
  });
  
  console.log('Document uploaded to category:', result.categoryId);
  return result;
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-to-specific-folder">

#### Upload to specific folder

Upload files directly to a specific folder within a category for more granular organization.

```
async function uploadToFolder() {
  const result = await ckbox.uploader.uploadFile('./report.xlsx', {
    folderId: '{{folderId}}'
  });
  
  console.log('File uploaded to folder:', result.folderId);
  return result;
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-with-progress-tracking">

#### Upload with progress tracking

Monitor upload progress in real-time with callback functions to update your UI or log progress.

```
async function uploadWithProgress() {
  const result = await ckbox.uploader.uploadFile('./large-file.mp4', {
    onProgress: (progress) => {
      const { loaded, total, progress: percent } = progress;
      console.log(`Progress: ${percent}% (${loaded}/${total} bytes)`);
      
      // Update progress bar in your UI
      updateProgressBar(percent);
    }
  });
  
  console.log('Upload completed:', result.id);
  return result;
}

function updateProgressBar(percent) {
  const progressBar = '█'.repeat(Math.floor(percent / 5));
  const empty = '░'.repeat(20 - Math.floor(percent / 5));
  console.log(`[${progressBar}${empty}] ${percent}%`);
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--multi-file-upload">

#### Multi-File upload

Handle batch uploads by processing multiple files sequentially with comprehensive error handling.

```
async function uploadMultipleFilesSequential(filePaths) {
  const results = [];
  
  for (const filePath of filePaths) {
    try {
      console.log(`Uploading: ${filePath}`);
      
      const result = await ckbox.uploader.uploadFile(filePath, {
        onProgress: (progress) => {
          console.log(`${filePath}: ${progress.progress}%`);
        }
      });
      
      results.push(result);
      console.log(`✅ Completed: ${filePath}`);
      
    } catch (error) {
      console.error(`❌ Failed: ${filePath}`, error.message);
      results.push({ error: error.message, filePath });
    }
  }
  
  return results;
}

// Usage
const files = ['./image1.jpg', './image2.png', './document.pdf'];
const results = await uploadMultipleFilesSequential(files);

```

<a id="ckbox/latest/features/sdk/backend-sdk/file-upload.html--upload-response">

### Upload response

Every successful file upload returns a `CKBoxAsset` object representing the uploaded file. Note that some properties like image metadata are processed asynchronously after upload, so metadata fields may be populated with a delay.

```
interface CKBoxAsset {
    id: string;                   // Unique identifier for the asset
    name: string;               // Original filename with extension
    categoryId: string;           // ID of the category where the file is stored
    folderId?: string;           // Optional folder ID within the category
    imageUrls?: {               // Generated image variants (thumbnails, resized versions)
        [key: string]: string; // Size name mapped to image URL
    };
    url: string;               // Direct access URL to the file
    size: number;               // File size in bytes
    lastUsedAt: string;           // ISO timestamp when the asset was last accessed
    lastModifiedAt: string;       // ISO timestamp when the asset was uploaded/modified
    path: string;               // Full path within CKBox storage structure
    tags: string[];               // Array of tags associated with the asset
    metadata?: {               // Optional metadata (populated asynchronously for images)
      width?: number;           // Image width in pixels
      height?: number;           // Image height in pixels
      metadataProcessingStatus?: string; // Processing status: 'queued', 'success', 'error',
      analysisProcessingStatus?: string; // AI processing status (if applicable): 'queued', 'success', 'error', 'skipped'
    };
}

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html">source file: "ckbox/latest/features/sdk/backend-sdk/installation.html"</a>

## Installation & Setup

This guide will walk you through installing and setting up the CKBox Node.js SDK in your project. By the end of this guide, you’ll have the SDK installed and be ready to make your first API calls.

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--prerequisites">

### Prerequisites

Before installing the CKBox Node.js SDK, ensure your environment meets these requirements:

* **Node.js**: Version 16.0.0 or higher
* **Package Manager**: npm, yarn, or pnpm
* **Module System**: ES modules support (the SDK is designed for modern Node.js applications)

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--package-installation">

### Package Installation

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--using-npm">

#### Using npm

```
npm install @ckbox/sdk-node

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--using-yarn">

#### Using yarn

```
yarn add @ckbox/sdk-node

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--using-pnpm">

#### Using pnpm

```
pnpm add @ckbox/sdk-node

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--obtaining-access-credentials">

### Obtaining Access Credentials

Before you can use the SDK, you need to obtain your API credentials from the CKBox Customer Portal.

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--what-is-an-access-key">

#### What is an Access Key?

The **Access Key** is a secret credential that authenticates your application with CKBox services. It’s used to generate JWT tokens that authorize API requests. This key should be kept secure and never exposed in client-side code.

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--getting-your-credentials">

#### Getting Your Credentials

1. **Log in to Customer Portal**

  * Visit the [Customer Portal](https://portal.ckeditor.com/)
  * Sign in with your account credentials
2. **Navigate to API Credentials**

  * Go to the Subscription -> Cloud environments
  * Select “Access credentials” from the sidebar
3. **Create or Copy Access Key**

  * If you don’t have an access key, click “Create a new access key”
  * Copy your existing access key if you already have one
4. **Get Environment ID**

  * In the Cloud environments tab copy the Environment ID for the environment you want to use
  * You can have multiple environments (e.g., development, staging, production)

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--security-best-practices">

#### Security Best Practices

⚠️ **Never commit your access key to version control**

Store your credentials using environment variables:

```
# .env file (add to .gitignore)
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--basic-setup">

### Basic Setup

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--1-import-the-sdk">

#### 1\. Import the SDK

```
// ES modules (recommended)
import CKBox from '@ckbox/sdk-node';

// CommonJS (if needed)
const { default: CKBox } = require('@ckbox/sdk-node');

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--2-configure-environment-variables">

#### 2\. Configure Environment Variables

Create a `.env` file in your project root:

```
# Required credentials
CKBOX_ACCESS_KEY=your_access_key_here
CKBOX_ENVIRONMENT_ID=your_environment_id_here

# Optional settings
CKBOX_WORKSPACE_ID=your_workspace_id
CKBOX_SERVICE_ORIGIN=https://api.ckbox.io

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--3-initialize-the-sdk">

#### 3\. Initialize the SDK

```
import CKBox from '@ckbox/sdk-node';
import 'dotenv/config'; // Load environment variables

// Basic configuration
const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID
});

// Access the main components
const { uploader, assets } = ckbox;

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--step-by-step-first-implementation">

### Step-by-Step First Implementation

Let’s create a complete example that demonstrates uploading a file and retrieving it:

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--1-create-project-structure">

#### 1\. Create Project Structure

```
mkdir ckbox-example
cd ckbox-example
npm init -y
npm install @ckbox/sdk-node dotenv

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--2-bootstrap-ckbox-object">

#### 2\. Bootstrap CKBox object

```
// upload-example.js
import 'dotenv/config';
import fs from 'fs';
import CKBox from '@ckbox/sdk-node';

export const ckbox = new CKBox({
  accessKey: process.env.CKBOX_ACCESS_KEY,
  environmentId: process.env.CKBOX_ENVIRONMENT_ID,
  // Optional: specify user context
  userId: 'user-123',
  userName: 'John Doe',
  role: 'user'
});

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--3-create-your-first-upload-script">

#### 3\. Create Your First Upload Script

```
// upload-example.js
...

async function uploadFile() {
  try {
    // Upload a file with progress tracking
    console.log('Starting file upload...');
    
    const result = await ckbox.uploader.uploadFile('./sample-image.jpg', {
      onProgress: (progress) => {
        console.log(`Upload progress: ${progress.progress}%`);
      }
    });
    
    console.log('Upload successful!');
    console.log('Asset ID:', result.id);
    console.log('File URL:', result.url);
    
    return result;
  } catch (error) {
    console.error('Upload failed:', error.message);
    throw error;
  }
}

// Run the upload
uploadFile()
  .then(asset => {
    console.log('✅ Upload completed successfully');
  })
  .catch(error => {
    console.error('❌ Upload failed:', error);
  });

```

<a id="ckbox/latest/features/sdk/backend-sdk/installation.html--4-test-your-setup">

#### 4\. Test Your Setup

```
# Add a test image to your project directory
# Run the upload script
node upload-example.js

```

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html">source file: "ckbox/latest/features/sdk/backend-sdk/overview.html"</a>

## Node.js SDK Overview

The **CKBox Node.js SDK** (`@ckbox/sdk-node`) is a lightweight, JavaScript library that provides seamless integration between your Node.js applications and CKBox services. This SDK is designed to bootstrap core CKBox functionality with minimal setup, allowing developers to quickly implement file upload capabilities and asset management features.

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--purpose-and-key-benefits">

### Purpose and Key Benefits

The Node.js SDK serves as a bridge between your server-side Node.js applications and the CKBox API, providing:

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--minimal-setup-integration">

#### **Minimal Setup Integration**

* **Zero-configuration approach** \- Get started with just a few lines of code
* **Smart defaults** \- Sensible configuration defaults reduce boilerplate
* **JWT-based authentication** \- Secure, token-based authentication handled automatically

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--comprehensive-upload-functionality">

#### **Comprehensive Upload Functionality**

* **Multiple upload methods** \- Support for files, buffers, and streams
* **Progress tracking** \- Real-time upload progress monitoring
* **Concurrent uploads** \- Built-in queue management with configurable concurrency limits
* **Error handling** \- Robust error management with detailed error information

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--asset-management">

#### **Asset Management**

* **Asset retrieval** \- Fetch individual assets or paginated lists
* **Advanced filtering** \- Search and filter assets by category, folder, and other criteria
* **Asset operations** \- Delete assets and manage your file library

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--enterprise-ready-features">

#### **Enterprise-Ready Features**

* **TypeScript support** \- Full type definitions for enhanced development experience
* **Workspace isolation** \- Multi-tenant architecture support
* **Role-based access** \- Granular permission control (user, admin, superadmin)
* **Error resilience** \- Comprehensive error handling and recovery

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--use-cases">

### Use Cases

The CKBox Node.js SDK is perfect for:

* **Content Management Systems** \- Integrate file upload and management into your CMS
* **E-commerce Platforms** \- Handle product images and documentation
* **Collaboration Tools** \- Enable file sharing and collaborative editing
* **Document Processing** \- Upload and manage documents, PDFs, and media files
* **Media Libraries** \- Build sophisticated media management applications
* **API Backends** \- Add file handling capabilities to REST APIs

<a id="ckbox/latest/features/sdk/backend-sdk/overview.html--getting-started">

### Getting Started

To begin using the CKBox Node.js SDK, you’ll need:

1. **CKBox plan** \- Sign up for CKEditor + CKBox
2. **Access Credentials** \- Obtain your `accessKey` and `environmentId` from the Customer Portal
3. **Node.js Environment** \- Node.js 16+

The next sections will guide you through installation, configuration, and implementing your first file upload.

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html">source file: "ckbox/latest/features/sdk/frontend-sdk/configuration-options.html"</a>

## CKBox Uploader widget configuration options

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--required-properties">

### Required Properties

| Property | Type               | Description                                                                                                                                    |
| -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| tokenUrl | string \| function | The URL of the [token endpoint](#ckbox/latest/guides/configuration/authentication.html--token-endpoint) or a callback that provides the token. |

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--optional-properties">

### Optional Properties

| Property         | Type             | Description                                 |
| ---------------- | ---------------- | ------------------------------------------- |
| workspaceId      | string           | A unique identifier of your CKBox workspace |
| uploadCategoryId | string           | Target category for uploads                 |
| uploadFolderId   | string           | Target folder for uploads                   |
| onUpload         | function         | Callback triggered on successful upload     |
| language         | string \| object | UI language configuration                   |
| serviceOrigin    | string           | Sets the origin to use for the REST API     |

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--property-details">

### Property Details

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--tokenurl">

#### `tokenUrl`

**Type:** `string | function`  
**Required:** Yes

Authentication endpoint or callback function that provides JWT tokens for CKBox API access.

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--string-url">

##### String URL

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  tokenUrl: 'https://your-token-endpoint.com/auth',
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--callback-function">

##### Callback Function

```
mountUploaderWidget(document.querySelector('#ckbox'), {
    tokenUrl: () =>
        new Promise((resolve, reject) => {
            const xhr = new XMLHttpRequest();

            xhr.open('GET', 'https://your.token.url');

            xhr.addEventListener('load', () => {
                const statusCode = xhr.status;
                const xhrResponse = xhr.response;

                if (statusCode < 200 || statusCode > 299) {
                    return reject(new Error('Cannot download new token!'));
                }

                return resolve(xhrResponse);
            });

            xhr.addEventListener('error', () => reject(new Error('Network Error')));
            xhr.addEventListener('abort', () => reject(new Error('Abort')));

            xhr.send();
        }),
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--workspaceid">

#### `workspaceId`

**Type:** `string`  
**Required:** No

The unique identifier of your CKBox workspace. This determines which workspace the uploader widget will connect to.

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--uploadcategoryid">

#### `uploadCategoryId`

**Type:** `string`  
**Required:** No

Specifies the target category for uploads. Files will be uploaded directly to this category, respecting its file type restrictions.

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  uploadCategoryId: 'images-category-id',
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--uploadfolderid">

#### `uploadFolderId`

**Type:** `string`  
**Required:** No

Specifies the target folder for uploads. Files will be uploaded directly to this folder within the specified category.

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  uploadFolderId: 'specific-folder-id',
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--onupload">

#### `onUpload`

**Type:** `function`  
**Required:** No

Callback function triggered when a file is successfully uploaded. Receives the uploaded asset data.

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  onUpload: (asset) => {
    console.log('File uploaded:', asset);
    // Handle successful upload
    // asset contains: id, name, extension, url, size, etc.
  },
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/configuration-options.html--serviceorigin">

#### `serviceOrigin`

**Type:** `string`  
**Required:** No

Custom CKBox API endpoint. Only needed for on-premises installations.

```
mountUploaderWidget(document.querySelector('#ckbox'), {
  workspaceId: 'your-workspace-id',
  tokenUrl: 'your-token-url',
  serviceOrigin: 'https://your-ckbox-api.com',
  // ... other options
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/example.html">source file: "ckbox/latest/features/sdk/frontend-sdk/example.html"</a>

## Example

This example demonstrates how to integrate the CKBox Uploader Widget into a simple content management system. The uploader widget provides a focused file upload interface that can be easily embedded into any web application.

<a id="ckbox/latest/features/sdk/frontend-sdk/example.html--use-cases">

### Use Cases

This pattern is ideal for:

* Blog post creation interfaces.
* Document management systems.
* Content creation tools.
* Any application requiring file upload functionality.

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html">source file: "ckbox/latest/features/sdk/frontend-sdk/installation.html"</a>

## Installation

The CKBox Uploader Widget is distributed as an npm package or as a package served from CDN.

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--node-package">

### Node package

To install CKBox Uploader Widget as an NPM dependency, run:

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--using-npm">

#### Using npm

```
npm install @ckbox/uploader

```

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--using-yarn">

#### Using yarn

```
yarn add @ckbox/uploader

```

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--using-pnpm">

#### Using pnpm

```
pnpm add @ckbox/uploader

```

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--cdn-server">

### CDN Server

To start using Uploader Widget on your website, embed the following `<script>` tag in the HTML of the page:

```
<script src="https://cdn.ckbox.io/uploader/2.11.1/ckboxWidget.js"></script>

```

Quick implementation example:

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckbox.io/uploader/2.11.1/ckboxWidget.js"></script>
    </head>
    <body>
        <div id="uploader"></div>
        <script>
            CKBoxWidget.mountUploaderWidget(document.getElementById('uploader'), {
                tokenUrl: 'https://your-token-endpoint.url',
                workspaceId: 'your-workspace-id',
            });
        </script>
    </body>
</html>

```

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--javascript">

### JavaScript

Once you install CKBox Uploader Widget, you can instantiate it in your code as shown below.

```
import { mountUploaderWidget } from '@ckbox/uploader';
import '@ckbox/uploader/dist/styles/ckbox.css';

const { unmount } = mountUploaderWidget(document.querySelector('#ckbox'), {
    workspaceId: 'your-workspace-id',
    tokenUrl: 'https://your-token-endpoint.url',
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/installation.html--react-integration">

### React integration

If you would like to use CKBox Uploader Widget in a React application, you can use the `CKBoxWidget` React component directly. It is exported by the `@ckbox/uploader` package.

Shown below is the content of an example React component file:

```
import * as React from "react";
import { CKBoxWidget } from '@ckbox/core';
import '@ckbox/uploader/dist/styles/ckbox.css';


function App() {
    return (
        <CKBoxWidget
            workspaceId="your-workspace-id"
            tokenUrl="https://your-token-endpoint.url"
        />
    );
}

export default App;

```

<a id="ckbox/latest/features/sdk/frontend-sdk/overview.html">source file: "ckbox/latest/features/sdk/frontend-sdk/overview.html"</a>

## Uploader overview

The CKBox Uploader Widget is a component designed to provide a streamlined file upload interface for integrating CKBox’s file uploading capabilities into any application. It offers a focused, lightweight solution for file uploads without the full CKBox workspace interface.

This uploader widget is ideal for applications that need file upload functionality without the complexity of a full-fledged file management interface, making it perfect for content management systems, document editors, and media-rich applications.

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html">source file: "ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html"</a>

## Uploader Widget Troubleshooting

This guide provides best practices and troubleshooting tips for the CKBox Uploader Widget to help you resolve common issues.

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--error-state-display">

### Error State Display

The uploader widget is designed to handle errors and display them to users. When an error occurs:

* The widget will automatically display an error state with a user-friendly message.
* Users will see a clear indication that something went wrong.
* The error dialog will show the error type and a compact message when available.

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--debugging-with-developer-tools">

### Debugging with Developer Tools

For detailed error information and debugging:

1. **Open Developer Tools**: Press `F12` to open your browser’s debugging tools.
2. **Check Console**: Look in the Console tab for detailed error messages.
3. **Network Tab**: Check network requests to identify authentication or API issues.

The developer tools will provide more detailed information than what is displayed in the user interface, making it easier to diagnose and resolve issues.

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--common-error-scenarios">

### Common Error Scenarios

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--invalid-token-url">

#### Invalid Token URL

**Symptoms:**

* Widget displays error state.
* Console shows authentication errors.
* Network requests return 401/403 status codes.

**Solutions:**

* Verify the `tokenUrl` parameter is correctly set.
* Ensure the token endpoint is accessible and returns valid tokens.
* Check that the token URL is using the correct protocol (`https://`).
* Verify the token endpoint is not blocked by CORS policies.

```
// Correct token URL format
CKBoxWidget.mountUploaderWidget(document.getElementById('ckbox'), {
    tokenUrl: 'https://your-domain.com/api/ckbox/token'
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--invalid-workspace-id">

#### Invalid Workspace ID

**Symptoms:**

* Widget fails to load or shows error state.
* Network requests return 404/403 status codes.

**Solutions:**

* Verify the `workspaceId` parameter matches your CKBox workspace.
* Check that the workspace ID is properly formatted.
* Ensure the workspace exists and is accessible with your token.
* Verify the workspace ID is not empty or undefined.

```
// Correct workspace ID usage
CKBoxWidget.mountUploaderWidget(document.getElementById('ckbox'), {
    tokenUrl: 'https://your-domain.com/api/ckbox/token',
    workspaceId: 'your-workspace-id-here'
});

```

<a id="ckbox/latest/features/sdk/frontend-sdk/troubleshooting.html--authentication-failures">

#### Authentication Failures

**Symptoms:**

* Widget shows authentication error.
* Console shows 401 Unauthorized errors.
* Token refresh failures.

**Solutions:**

* Verify token endpoint returns valid JWT tokens.
* Check token expiration and refresh logic.
* Ensure proper authentication headers.
* Verify token has necessary permissions for the workspace.

<a id="ckbox/latest/features/sdk/overview.html">source file: "ckbox/latest/features/sdk/overview.html"</a>

## SDK Overview

The CKBox SDK provides a quick and efficient way to bootstrap CKBox functionality in your applications with minimal overhead. Designed for developers who need to integrate file upload and asset management capabilities rapidly, the SDK abstracts away the complexity of API interactions while maintaining full control over the underlying functionality.

The SDK is perfect for developers who want to focus on building their application features rather than dealing with the intricacies of file management infrastructure.

<a id="ckbox/latest/features/webhooks/events.html">source file: "ckbox/latest/features/webhooks/events.html"</a>

## Events

Each event corresponds with a certain action that can happen in CKBox in a certain environment. Also, each event has a specific payload format with the relevant event information.

Before you use Webhooks, please get familiar with the basic principles of the feature. You can read more about using Webhooks in the [Overview](#ckbox/latest/features/webhooks/overview.html) guide.

<a id="ckbox/latest/features/webhooks/events.html--assets">

### Assets

You can trigger the following events for assets in CKBox.

<a id="ckbox/latest/features/webhooks/events.html--asset-uploaded">

#### Asset uploaded

Name: `asset.uploaded`  
Description: Triggered whenever the file is uploaded to a category or a folder.

<a id="ckbox/latest/features/webhooks/events.html--payload">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the uploaded asset.
* `user` – The details of a user performing this action.

<a id="ckbox/latest/features/webhooks/events.html--example">

##### Example

The following example presents a webhook request sent after a user uploads a file.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.uploaded',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: '-1zT3SPzjuEv',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 523625,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:03:18.815Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--asset-modified">

#### Asset modified

Name: `asset.modified`  
Description: Triggered when the asset is modified.

<a id="ckbox/latest/features/webhooks/events.html--payload-2">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the modified asset.
* `asset_before_modification` – A snapshot of the asset before modification.
* `user` – The details of a user performing this action.

<a id="ckbox/latest/features/webhooks/events.html--example-2">

##### Example

The following example presents a webhook request sent after a user modifies an asset.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.modified',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: '-1zT3SPzjuEv',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 523625,
            tags: [ 'foo' ],
            metadata: { 
                description: 'Updated description!', 
                custom_attributes: {}
            }
        },
        asset_before_modification: {
            id: '-1zT3SPzjuEv',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 523625,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:07:34.497Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--asset-removed">

#### Asset removed

Name: `asset.removed`  
Description: Triggered when the asset is removed.

<a id="ckbox/latest/features/webhooks/events.html--payload-3">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the removed asset.
* `user` – The details of a user performing this action.

<a id="ckbox/latest/features/webhooks/events.html--example-3">

##### Example

The following example presents a webhook request sent after a user removes an asset.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.removed',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: '-1zT3SPzjuEv',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/-1zT3SPzjuEv/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 523625,
            tags: [ 'foo' ],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:09:52.989Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--asset-copied">

#### Asset copied

Name: `asset.copied`  
Description: Triggered when the asset is copied.

<a id="ckbox/latest/features/webhooks/events.html--payload-4">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the removed asset.
* `source_asset` – The details of the source asset.
* `user` – The details of a user performing this action.

<a id="ckbox/latest/features/webhooks/events.html--example-4">

##### Example

The following example presents a webhook request sent after a user copies an asset.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.copied',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: 'ZXs11paEIP72',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/ZXs11paEIP72/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            folder_id: 'W_g4u6ZEHxuO',
            size_in_bytes: 523625,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        source_asset: {
            id: '_DpyO7eRxHtT',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 523625,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:29:11.602Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--asset-overwritten">

#### Asset overwritten

Name: `asset.overwritten`  
Description: Triggered when the asset’s content is overwritten.

<a id="ckbox/latest/features/webhooks/events.html--payload-5">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the overwritten asset.
* `user` – The details of a user performing this action.

<a id="ckbox/latest/features/webhooks/events.html--example-5">

##### Example

The following example presents a webhook request sent after a user overwrites an asset.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.overwritten',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: '_DpyO7eRxHtT',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 203024,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:32:22.689Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--asset-cache-invalidated">

#### Asset cache invalidated

Name: `asset.cache.invalidated`  
Description: Triggered when the asset’s cache should be invalidated.

<a id="ckbox/latest/features/webhooks/events.html--payload-6">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `asset` – The details of the overwritten asset.
* `user` – The details of a user performing this action.
* `paths_to_be_invalidated` – A list of URL paths that should be invalidated.

<a id="ckbox/latest/features/webhooks/events.html--example-6">

##### Example

The following example presents a webhook request sent after an asset’s content changes and CDN paths should be invalidated.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'asset.overwritten',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        asset: {
            id: '_DpyO7eRxHtT',
            name: 'Cupcake',
            extension: 'jpeg',
            url: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/file',
            images_urls: {
                '192': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/192.webp',
                '384': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/384.webp',
                '576': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/576.webp',
                '768': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/768.webp',
                '960': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/960.webp',
                '1152': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1152.webp',
                '1344': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1344.webp',
                '1536': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1536.webp',
                '1728': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1728.webp',
                '1920': 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.webp',
                default: 'https://ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/1920.jpeg'
            },
            mime_type: 'image/jpeg',
            category_id: '1f0ca0db-d0fa-4b03-9703-9f152615ed0c',
            size_in_bytes: 203024,
            tags: [],
            metadata: { 
                description: 'An image of a cupcake', 
                custom_attributes: {}
            }
        },
        paths_to_be_invalidated: ['https://cdn.ckbox.dev/6afdca1ba1e38969dea1/assets/_DpyO7eRxHtT/images/192.webp']
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:32:22.689Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--folders">

### Folders

The following events can be triggered for folders in CKBox.

<a id="ckbox/latest/features/webhooks/events.html--folder-created">

#### Folder created

Name: `folder.created`  
Description: Triggered when a folder is created.

<a id="ckbox/latest/features/webhooks/events.html--payload-7">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `folder` – The details of the created folder.
* `user` – The details of a user performing this action

<a id="ckbox/latest/features/webhooks/events.html--example-7">

##### Example

The following example presents a webhook request sent after a user creates a folder.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'folder.created',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        folder: {
            id: 'hr8zl8N_8-un',
            name: 'Folder',
            category_id: '957165c8-bb91-4792-922d-72c572b5b12d'
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:41:37.953Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--folder-modified">

#### Folder modified

Name: `folder.modified`  
Description: Triggered when the folder is modified.

<a id="ckbox/latest/features/webhooks/events.html--payload-8">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `folder` – The details of the modified folder.
* `user` – The details of a user performing this action

<a id="ckbox/latest/features/webhooks/events.html--example-8">

##### Example

The following example presents a webhook request sent after a user modifies the folder.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'folder.modified',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        folder: {
            id: 'hr8zl8N_8-un',
            name: 'Images',
            category_id: '957165c8-bb91-4792-922d-72c572b5b12d'
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:42:42.351Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--folder-removed">

#### Folder removed

Name: `folder.removed`  
Description: Triggered when the folder is removed.

<a id="ckbox/latest/features/webhooks/events.html--payload-9">

##### Payload

* `workspace_id` – The identifier of the workspace for which the action was initialized.
* `folder` – The details of the removed folder.
* `user` – The details of a user performing this action

<a id="ckbox/latest/features/webhooks/events.html--example-9">

##### Example

The following example presents a webhook request sent after a user removes the folder.

```
{
    environment_id: '6afdca1ba1e38969dea1',
    event: 'folder.removed',
    payload: {
        workspace_id: '80e839331c4d8827c474',
        folder: {
            id: 'hr8zl8N_8-un',
            name: 'Images',
            category_id: '957165c8-bb91-4792-922d-72c572b5b12d'
        },
        user: { id: 'user-1', role: 'User' }
    },
    sent_at: '2024-02-18T18:43:30.861Z'
}

```

<a id="ckbox/latest/features/webhooks/events.html--next-steps">

### Next steps

* [Learn how to manage webhooks](#ckbox/latest/features/webhooks/management.html).
* [Read more about testing webhooks in a dedicated article](#ckbox/latest/features/webhooks/testing.html).
* [Check the list of events available in CKBox](#ckbox/latest/features/webhooks/events.html).

<a id="ckbox/latest/features/webhooks/management.html">source file: "ckbox/latest/features/webhooks/management.html"</a>

## Webhooks management

Webhooks management is available for every environment in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or the Management Panel for the On-Premises version.

Webhooks are managed separately for every environment. You can select the environment to manage from the list of environments by clicking the row with the environment of your choice.

<a id="ckbox/latest/features/webhooks/management.html--creating-a-webhook">

### Creating a webhook

The webhooks can be managed on a dedicated page. To switch to the Webhooks section, click the `Webhooks` tab.  
The page shows existing webhooks and a button to add new ones. The list is empty until you define some webhooks for a particular environment.

To create a new webhook, click the `Create a new webhook` button.

The “Creating a webhook” page will show up.

While creating a new webhook, you need to provide a `Webhook URL` that CKBox will send the requests to. The provided endpoint must be available from the CKBox On-premises application or from the Internet for the SaaS variant.

In the next section, you can configure the retry mechanism. If enabled, the webhooks will be resent in case the response code from the Webhook URL endpoint is larger than 299.

The Webhook request will be retried for of number of times provided in the `Max retries`, or until the response status 2xx will be returned.

Between each retry, there will be a delay, depending on the `Retry Interval in minutes` value.

The next section allows you to select [events](#ckbox/latest/features/webhooks/events.html) that will trigger the webhook.

A single webhook can be triggered by many events, depending on the needs.

[See the full list of available events in a dedicated article.](#ckbox/latest/features/webhooks/events.html)

To finish the process you need to click the `Save` button at the very bottom of the form.

The newly created Webhook will appear on the list in the main view of the `Webhooks` tabs.

<a id="ckbox/latest/features/webhooks/management.html--updating-a-webhook">

### Updating a webhook

Each webhook visible in this list can be edited. It can be done by clicking the `Edit` button.

The button will open the “Editing the webhook” view. It presents the same set of options as the “Create a new webhook” view.

You can change the Webhook URL, the set of events that will trigger the webhook and the settings of the retry mechanism.

To save the changes you need to click the `Save` button at the very bottom of the form.

You will be redirected to the list of created webhooks.

<a id="ckbox/latest/features/webhooks/management.html--removing-webhook">

### Removing webhook

To remove a webhook use the remove button with an icon of a trash bin next to the selected webhook.

You will see the prompt to confirm the removal.

<a id="ckbox/latest/features/webhooks/management.html--next-steps">

### Next steps

* [Read more about the webhooks request history in a dedicated article](#ckbox/latest/features/webhooks/requests.html).
* [Read more about testing webhooks in a dedicated article](#ckbox/latest/features/webhooks/testing.html).
* [Check the list of events available in CKBox](#ckbox/latest/features/webhooks/events.html).

<a id="ckbox/latest/features/webhooks/overview.html">source file: "ckbox/latest/features/webhooks/overview.html"</a>

## Webhooks

Webhooks resemble a notification mechanism that can be used to build integrations with CKBox. CKBox sends an HTTP `POST` request to a configured URL when specified events are triggered.

Webhooks can be used for data synchronization between CKBox and another system or to build a notifications system. For example, thanks to webhooks, the system might notify the users via email about changes made to the assets.

<a id="ckbox/latest/features/webhooks/overview.html--benefits-of-using-webhooks">

### Benefits of using webhooks

By using webhooks while integrating your application with the CKBox you can make the integration more reliable. Webhooks enable real-time communication by instantly notifying external systems about specific events, such as file uploads, asset modifications or deletions. This allows integrated systems to remain synchronized, facilitating prompt responses to changes. It therefore enhances flexibility, efficiency and scalability.

<a id="ckbox/latest/features/webhooks/overview.html--examples">

#### Examples

<a id="ckbox/latest/features/webhooks/overview.html--data-synchronization">

##### Data synchronization

Webhooks can serve as a notification system for events like file uploads, modifications, or removals. This can improve synchronization with other systems. For example, an integrated system can follow these notifications to synchronize folder trees in external systems.

<a id="ckbox/latest/features/webhooks/overview.html--triggering-other-operations">

##### Triggering other operations

Webhooks can initiate additional actions or processes in response to specific events detected by the webhook. For instance, upon receiving a notification of a file upload, a webhook can automatically trigger processes such as AI analysis, updating metadata, or notifying relevant stakeholders.

<a id="ckbox/latest/features/webhooks/overview.html--tracking-user-changes">

##### Tracking user changes

Webhooks allow for the detection of actions like file uploads, modifications, or deletions performed by users. By leveraging webhooks, applications can promptly notify external systems of these changes, enabling efficient synchronization and facilitating comprehensive tracking of user activity within the application ecosystem.

<a id="ckbox/latest/features/webhooks/overview.html--security">

### Security

Every webhook request sent from CKBox to the configured webhook URL has a signature and a timestamp. Thanks to this, every request received by the server can be checked and confirmed that it comes from CKBox and has not been modified.

More information about the verification process of signing requests can be found in the Request signature guide.

<a id="ckbox/latest/features/webhooks/overview.html--webhook-order">

### Webhook order

Please keep in mind that webhook events are sent asynchronously. You should, therefore, not rely on the order of the received events.

If the operations you are performing are order-sensitive, you should add another layer of verification to your endpoint that handles the events.

<a id="ckbox/latest/features/webhooks/overview.html--webhook-format">

### Webhook format

Each webhook request sent by CKBox has the following properties:

* `event` – The name of the event that triggered the webhook.
* `environment_id` – The ID of the environment.
* `sent_at` – The date when the specified webhook was sent.
* `payload` – The payload of the webhook. It contains the data about a specific event.

<a id="ckbox/latest/features/webhooks/overview.html--example">

#### Example

Below you can find an example of a sample webhook request sent by CKBox. It is triggered by a file uploaded to the environment with an ID of `user-1`.

```
{
  environment_id: '6afdca1ba1e38969dea1',
  event: 'asset.uploaded',
  payload: {
    workspace_id: '80e839331c4d8827c474',
    asset: {
      id: 'Ta1xyyjKGbvF',
      name: 'image',
      extension: 'jpeg',
      url: {{fileUrl}},
      images_urls: {{imageUrls}},
      mime_type: 'image/jpeg',
      category_id: '0055659e-464c-4ebf-bc4b-7b690fbdfb72',
      size_in_bytes: 21104,
      tags: [],
      metadata: {
        description: 'File description',
        custom_attributes: {}
      }
    },
    user: { id: 'user-1', role: 'User' }
  },
  sent_at: '2024-02-16T15:45:45.190Z'
}

```

<a id="ckbox/latest/features/webhooks/overview.html--next-steps">

### Next steps

* [Check the list of events available in CKBox](#ckbox/latest/features/webhooks/events.html).
* [Learn how to manage webhooks](#ckbox/latest/features/webhooks/management.html).

<a id="ckbox/latest/features/webhooks/requests.html">source file: "ckbox/latest/features/webhooks/requests.html"</a>

## Requests history

For each environment, there is a list of sent requests for each created webhook in the [Customer Portal](https://portal.ckeditor.com/) for SaaS or the Management Panel for On-Premises. Each request on the list can be resent and contains some relevant and useful information, such as:

* `request payload`,
* `request headers`,
* `response status`,
* `response body`,
* `response headers`.

The view of a particular request allows you to resent the webhook with the same data, as during the first call.

<a id="ckbox/latest/features/webhooks/requests.html--display-requests">

### Display requests

To display a list of requests sent by a particular webhook, you need to display a list of created webhooks for a particular environment.  
Then click the selected webhook from the list.

You will see the paginated list of the webhook’s requests. It comes with basic information like response status, the name of the event that triggered the webhook, and the time when it was sent.

<a id="ckbox/latest/features/webhooks/requests.html--filtering-requests">

### Filtering requests

The list of requests usually contains hundreds of requests. To make reviewing them easier, there is a possibility to filter them.

By using the filters above the list you can filter the request by response status, events, and range of time when they occurred. By default, the requests from the last hour are displayed.

You can select the date range or you can use the relative time frame.

All filters are saved in the URL of the list. It allows you to share the link with anyone who will need to see the exact, filtered list of requests.

<a id="ckbox/latest/features/webhooks/requests.html--details-of-request">

### Details of request

To check the details of a particular request click the event name or the icon with an eye on the right side of the selected row.

After selecting a particular request, you will see its details.

You can switch between Request and Response details, by using the `Request` and `Response` tabs at the top.

<a id="ckbox/latest/features/webhooks/requests.html--manual-resend">

### Manual resend

In case of failure of a server that receives the webhooks requests, you may need to manually resent a specific request to not lose data.

The request details view allows you to resend the request by using the `Resend the request` button.

You will be asked to confirm the action.

After the request is resent successfully, you will be return to the list of requests.

<a id="ckbox/latest/features/webhooks/requests.html--next-steps">

### Next steps

* [Read more about testing webhooks in a dedicated article](#ckbox/latest/features/webhooks/testing.html).
* [Check the list of events available in CKBox](#ckbox/latest/features/webhooks/events.html).

<a id="ckbox/latest/features/webhooks/server.html">source file: "ckbox/latest/features/webhooks/server.html"</a>

## Webhooks server

To work with incoming webhooks, an application that listens to HTTP `POST` requests sent from CKBox is needed.

**This application must be accessible from the Internet.**

<a id="ckbox/latest/features/webhooks/server.html--examples">

### Examples

Check an [example of a webhook server implementation in Node.js](#cs/latest/examples/webhooks/webhooks-server-nodejs.html).  
Check an [example of a webhook server implementation in PHP](#cs/latest/examples/webhooks/webhooks-server-php.html).

<a id="ckbox/latest/features/webhooks/testing.html">source file: "ckbox/latest/features/webhooks/testing.html"</a>

## Webhooks testing

A crucial part of any integration is testing. To this end, CKBox provides several tools that facilitate the testing of integration with webhooks.

<a id="ckbox/latest/features/webhooks/testing.html--ping-event">

### Ping event

After creating a webhook, CKBox sends a straightforward `ping` event that can be used to confirm that the integration works correctly.

Payload:

* `id` – The ID of the request.
* `url` – The URL of the request.

<a id="ckbox/latest/features/webhooks/testing.html--example">

#### Example

You can find an example of a `ping` event sent by CKBox below.

```
{
    "event": "ping",
    "environment_id": "environment-1",
    "payload": {
        "id": "id",
        "url": "url",
    },
    "sent_at": "2020-06-15T09:32:17.813Z"
}

```

<a id="ckbox/latest/features/webhooks/testing.html--next-steps">

### Next steps

* [Learn how to manage webhooks](#ckbox/latest/features/webhooks/management.html).
* [Read more about the request history in a dedicated article](#ckbox/latest/features/webhooks/requests.html).
* [Check the list of events available in CKBox](#ckbox/latest/features/webhooks/events.html).

<a id="ckbox/latest/guides/changelog.html">source file: "ckbox/latest/guides/changelog.html"</a>

## Changelog

<a id="ckbox/latest/guides/changelog.html--2111">

### 2.11.1

<a id="ckbox/latest/guides/changelog.html--other-changes">

#### Other changes

* Updated dependencies  
Selected dependencies have been updated to the latest versions, improving performance and security.

<a id="ckbox/latest/guides/changelog.html--2110-23022026">

### 2.11.0 (23.02.2026)

<a id="ckbox/latest/guides/changelog.html--features">

#### Features

* Semantic Search  
Enhances the existing [AI-powered features](#ckbox/latest/features/ai-features.html) by adding semantic search. Unlike keyword search, which matches exact words, semantic search understands the meaning and intent behind a query—so users can describe what they are looking for in natural language and find relevant assets even when the words do not appear in the asset metadata.
* Delete, copy, and move from search  
Enabled delete, copy, and move actions directly from the search results view. Previously, asset operations in search were limited to metadata editing. The full set of actions is now available when working with search results, speeding up the workflow when managing assets found through search queries.

<a id="ckbox/latest/guides/changelog.html--2101-05022026">

### 2.10.1 (05.02.2026)

<a id="ckbox/latest/guides/changelog.html--bug-fixes">

#### Bug fixes

* Fixed AI manual trigger banner showing for non-image assets  
The banner was incorrectly displayed for assets other than images. It is now shown only when viewing image assets.

<a id="ckbox/latest/guides/changelog.html--2100-03022026">

### 2.10.0 (03.02.2026)

<a id="ckbox/latest/guides/changelog.html--features-2">

#### Features

* Improved workspaces performance and management  
Workspaces received a major performance update along with several UX improvements aimed at streamlining management and navigation:

  * Updated Superadmin workspaces management view – The management view now features a paginated table containing a full list of all workspaces within the environment. To make finding specific data easier, users can now search for a workspace by both its name and its exact ID.
  * Updated workspaces dropdown – The workspace switcher has been redesigned to support searching by name and exact ID. Additionally, it now categorizes recently used workspaces, providing quick and convenient access to the most relevant environments.
* Direct metadata editing from search  
Enabled editing asset properties (name, tags, and description) directly from the search results view. Previously, these actions were only available when browsing via the category view. This change significantly speeds up the workflow when managing large sets of assets found through search queries.

<a id="ckbox/latest/guides/changelog.html--292-13102025">

### 2.9.2 (13.10.2025)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-2">

#### Bug fixes

* Fixed React dependency mismatch between CKBox packages  
Previously, `@ckbox/core` and `@ckbox/components` had peer dependencies to React v18, while the main `ckbox` package relied on React v19\. This mismatch could cause npm package manager to resolve peer dependencies incorrectly, which triggered React compatibility runtime errors in setups that utilized the main CKBox package.

<a id="ckbox/latest/guides/changelog.html--291-09102025">

### 2.9.1 (09.10.2025)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-3">

#### Bug fixes

* Fixed missing border on inline application mode

<a id="ckbox/latest/guides/changelog.html--290-06102025">

### 2.9.0 (06.10.2025)

<a id="ckbox/latest/guides/changelog.html--features-3">

#### Features

* ✨ Added [AI-powered features](#ckbox/latest/features/ai-features.html) ✨  
When enabled at the workspace level, image-like assets will receive automatically generated descriptions and tags via generative AI.
* Introduced [@ckbox/uploader](https://www.npmjs.com/package/@ckbox/uploader) package  
This is a lightweight, universal embeddable uploader component. It is useful for integrating upload functionality across frameworks without including the full CKBox UI or bundle.
* Introduced [@ckbox/sdk-node](https://www.npmjs.com/package/@ckbox/sdk-node) package  
A Node.js integration for programmatic asset management and uploads has been added. It provides APIs to manage and upload assets directly from server-side code.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-4">

#### Bug fixes

* Fixed asset restoration tags bug  
When an asset was restored from trash, its original tags could be overwritten. Now tags are correctly preserved and restored along with the asset.

<a id="ckbox/latest/guides/changelog.html--282-20082025">

### 2.8.2 (20.08.2025)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-5">

#### Bug fixes

* Fixed an issue with the description input in the CKBox properties drawer.  
Recent Chromium-based browsers changed the way textarea sizes are calculated, which caused the input field to collapse.  
The input behavior has been adjusted to ensure consistent rendering across all supported browsers.

<a id="ckbox/latest/guides/changelog.html--281-13082025">

### 2.8.1 (13.08.2025)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-6">

#### Bug fixes

* Fixed a visual glitch that occurred when selecting an asset in the Trash and navigating directly to a category without an onChoose callback attached.  
Previously, this caused an unintended validation notification to appear during the switch.

<a id="ckbox/latest/guides/changelog.html--280-11062025">

### 2.8.0 (11.06.2025)

<a id="ckbox/latest/guides/changelog.html--features-4">

#### Features

* Introduced the Trash Bin feature  
This feature introduces soft-delete mechanism for assets, allowing users to recover accidentally deleted files, auto-purge old items, and better manage asset lifecycle.
* Added a warning for dangerous file extensions  
Admins will now receive a warning when attempting to allow potentially dangerous file extensions (e.g. `exe`, `js`, `html`) in a category’s allowed extensions. This helps prevent accidental upload of executable or scriptable files that could pose security risks when accessed through browsers or operating systems.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-and-upgrades">

#### Bug fixes and upgrades

* Improved wording, communication and modernized overall look of the CKBox UI.
* Selected dependencies have been updated to the latest versions, improving performance and security.
* Updated React to v19

<a id="ckbox/latest/guides/changelog.html--260-14102024">

### 2.6.0 (14.10.2024)

<a id="ckbox/latest/guides/changelog.html--features-5">

#### Features

* Introduced the ability to set a custom thumbnail for non-image assets  
Added a new endpoint `POST:/assets/{{assetId}}/thumbs` which allows to upload an image that would become a custom thumbnail of the asset.
* Introduced [Private Categories](#ckbox/latest/features/private-categories.html)  
The feature will give administrators the ability to mark certain categories of assets as private, restricting access to its assets to selected users or groups, adding an additional layer of control over content sharing.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-7">

#### Bug fixes

* Updated dependencies

<a id="ckbox/latest/guides/changelog.html--250-01082024">

### 2.5.0 (01.08.2024)

<a id="ckbox/latest/guides/changelog.html--features-6">

#### Features

* Introduced [Permissions feature](#ckbox/latest/features/permissions.html):  
Permissions enable fine-grained control over user access to specific features and actions. By assigning permissions, admins can regulate user interactions with assets, categories, and folders.  
Permissions introduce control over:  
  * **Accessing a Category**
  * **Creating an Asset**
  * **Deleting an Asset**
  * **Modifying an Asset**
  * **Modifying Asset Metadata**
  * **Creating a Folder**
  * **Modifying a Folder Metadata**
  * **Deleting a Folder**

<a id="ckbox/latest/guides/changelog.html--bug-fixes-8">

#### Bug fixes

* Improved the performance of Workspaces  
Workspace information is fetched in a more optimized way.
* Fixed problem with “Forbidden Operation” notification for some pricing plans in admin panel
* Updated dependencies

<a id="ckbox/latest/guides/changelog.html--240-29022024">

### 2.4.0 (29.02.2024)

<a id="ckbox/latest/guides/changelog.html--features-7">

#### Features

* Introduced [Webhooks](#ckbox/latest/features/webhooks/overview.html)  
By integrating webhooks, third-party apps will receive notifications for various events, including:

  * `asset-uploaded` when an asset would be uploaded,
  * `asset-modified` when an asset would be modified,
  * `asset-overwritten` when an asset would be overwritten,
  * `asset-copied` when an asset would be copied,
  * `asset-cache-invalidated` when an asset cache should be invalidated,
  * `folder-created` when a folder would be created,
  * `folder-modified` when a folder would be modified,
  * `folder-removed` when a folder would be removed.
* Introduced the possibility to whitelist file types to interact with.  
Introduced a new configuration option [choosableFileExtensions](#ckbox/latest/guides/configuration/configuration-options.html--choosablefileextensions) which will allow developers to define a list of permitted file extensions, allowing a more controlled environment. Whitelisted file types will be enabled for interaction and selection within the CKBox, customizing the behavior of **`assets.onChoose`**.
* Improved Image Editor  
Image Editor will suggest a new filename when saving an image as a new file, enhancing user experience.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-9">

#### Bug fixes

* Improvement of the overall performance.
* Enhancements to improve connection stability.  
Addressed and resolved potential issues that may have led to connection disruptions.

<a id="ckbox/latest/guides/changelog.html--231-07122023">

### 2.3.1 (07.12.2023)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-10">

#### Bug fixes

* Improved behavior of maximized mode  
Fixed issue where it would be possible to scroll the content underneath the maximized window.  
Fixed page elements sometimes being rendered on top of the maximized window.

<a id="ckbox/latest/guides/changelog.html--230-06122023">

### 2.3.0 (06.12.2023)

<a id="ckbox/latest/guides/changelog.html--features-8">

#### Features

* Allow editing external images in the standalone image editor.  
Recently introduced standalone image editor that is available as a separate component, mounted using `mountImageEditor` method via ckbox package can now handle external images. This expands the editor’s capabilities to edit images from external online sources. The image will be previously downloaded and uploaded to CKBox. After editing, the result will be available in CKBox storage.  
Note: CORS restrictions apply.
* Introduced a maximized mode.  
CKBox’s user interface will be expandable to fullscreen mode using a dedicated Maximize/Minimize button on the top-bar.
* Allow to easily open images/pdf files in a new tab.  
Images and PDF files will be easily openable in a new tab using the dedicated “Open in a new tab” button on the asset preview.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-11">

#### Bug fixes

* Improved error handling.  
Improved displaying `traceId` details in public errors displayed in the case of potential problems with the application.
* Improved JWT validation.  
JWT `auth.ckbox.workspaces` empty array validation was added.

<a id="ckbox/latest/guides/changelog.html--220-14112023">

### 2.2.0 (14.11.2023)

<a id="ckbox/latest/guides/changelog.html--features-9">

#### Features

* Introduced a feature that enables to globally manage environment allowed extensions.  
Users with the `superadmin` role will now be allowed to control the allowed extensions globally in CKBox throughout all workspaces. SuperAdmins can restrict which files can be uploaded to the environment, and which cannot. If global limitation of extensions is enabled, administrators managing categories will be able to limit extensions in a category only to the selected set of file extensions.
* Introduced the Workspace Templates feature.  
Workspace Templates let `superadmin` users streamline workspace initialization. With this feature, `superadmin` users gain the ability to control the default set of categories for newly created workspaces. This feature empowers administrators with greater control and flexibility of workspace configuration.
* Upgraded the `tokenUrl` configuration option.  
The `tokenUrl` configuration option can, in addition to the standard approach with passing the URL to the token endpoint, also be a callback that provides a promisified token.
* Introduced the standalone image editor.  
CKBox package now exposes a standalone component for image editing only.  
CKBox’s internal image editor can be started via the `mountImageEditor` method, allowing for the edition of a given image asset.
* Introduced a basic mobile devices support.  
CKBox is now adapted to lower screen resolution devices on some limited scope.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-12">

#### Bug fixes

* Corrected an error related to loss of workspace access during CKBox runtime.  
If a user lost access to the current workspace, CKBox will attempt to redirect them to a new initial workspace. User workspace access is determined based on the info from the token.
* Fixed the cache invalidation problem during Workspace management.  
Fixed refreshing issues of workspaces list while `superadmin` manages workspaces, e.g. deletes or adds workspace.
* Resolved the drawer overflow issues.  
Fixed the problem of unscrollable content if drawer content exceeds available viewport.
* Disabled the auto-scrolling on focus.  
Fixed the problem of CKBox autoscrolling issues while focusing on particular elements of CKBox interface.

<a id="ckbox/latest/guides/changelog.html--210-31082023">

### 2.1.0 (31.08.2023)

<a id="ckbox/latest/guides/changelog.html--features-10">

#### Features

* Introduced UI for [Workspaces](#ckbox/latest/features/file-management/workspaces.html) feature.  
Users with the `superadmin` role can manage workspaces in a dedicated view within Settings. The UI allows to add, remove, and rename workspaces.
* Improve UI for navigation through workspaces.  
The active workspace is now displayed even if the navigation bar is collapsed. Each workspace is additionally represented by an avatar.
* Save user preferences per workspace.  
The following properties will be remembered per workspace: Last used view, last search query, and search history.
* Introduced configuration options for minimizing upload dialog and hiding upload components.  
Option [upload.dialogMinimizeTimeout](#ckbox/latest/guides/configuration/configuration-options.html--uploaddialogminimizetimeout) can be used to configure timeout for minimizing upload dialog after completed upload.  
Option [upload.componentsHideTimeout](#ckbox/latest/guides/configuration/configuration-options.html--uploadcomponentshidetimeout) can be used to configure timeout for hiding all upload components after completed upload.
* Remember the last used workspace.  
The last used workspace is saved and CKBox will try to use it the next time it is initialized. If a workspace is removed by then, the first workspace defined in the token will be initialized instead.
* Remember the opened / closed state of the properties drawer.  
The opened / closed state of the properties drawer is saved and CKBox will use it the next time it is initialized.
* Display the modification date in the properties drawer.  
The properties drawer contains the modification date of the selected asset. Hovering over either a modification or upload date displays the exact modification / upload time.
* Loader is displayed in image editing as long as the image is being fetched.  
Until an image is fully loaded any interaction with the feature is disabled.
* Focus CKBox dialog on mount.  
CKBox dialog will receive focus once it is opened. This is a two-step process: First, the main dialog `div` will receive focus followed by an active navigation item (if there is one). The mechanism will work only if CKBox is in [dialog](#ckbox/latest/guides/configuration/configuration-options.html--dialog) mode.
* Introduced `lark` theme.  
The new theme is styled after the default theme of CKEditor 5.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-13">

#### Bug fixes

* Fixes issues related to copying / pasting assets with the clipboard.  
Assets pasting from the clipboard did not work correctly in Safari. The issue has been fixed.  
In Firefox the feature will not work at all unless the user enables the `dom.events.asyncClipboard.clipboardItem` flag in the `about:config` settings in their browser.
* Remove UTF-8 space separators from the stylesheet.  
Until now CKBox used a few of such characters. They could be misinterpreted by the browser if the host application was not configured to use UTF-8.
* Image resize fields are now part of the form in the save dialog.  
Image editing changes can be now submitted with keyboard if one of the image resize fields is focused.
* Validate image resize fields in the save dialog.  
Image resize fields are now properly validated. The maximum allowed value for a single dimension is 16383 px. In addition, the new size cannot exceed the maximum image resolution for the used CKBox plan.
* Ignore the `auth.ckbox.workspaces` field in the token if the user is a superadmin.  
Since users with the `superadmin` role have access to all workspaces, setting the field in the token won’t have any effect.
* Add missing translations.  
Several messages were missing proper translations, e.g. predefined dates in the search dialog.

<a id="ckbox/latest/guides/changelog.html--200-28072023">

### 2.0.0 (28.07.2023)

<a id="ckbox/latest/guides/changelog.html--features-11">

#### Features

* Introduced the PDF preview feature.  
PDF documents can be now opened directly in CKBox after clicking the `View` button in the toolbar.
* Added the [view.onChange](#ckbox/latest/guides/configuration/configuration-options.html--viewonchange) configuration option.  
These options allow to define a callback triggered each time the user view changes, i.e. user changes the folder, moves to search results, or to recently used files.
* Introduced the `url` and `imageUrls` attributes in the [asset model](https://api.ckbox.io/api/docs#tag/Assets/operation/getAsset) of the CKBox REST API.  
The URLs to assets and to the responsive versions of images are now returned in the CKBox REST API responses.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-14">

#### Bug fixes

* Fixed an issue related to applying crop, rotate, and flip to the edited image.  
When a crop, rotate and flip operations were applied together on the edited image, after saving changes the server returned an error and the changes were not applied. The issue has been fixed and all the operations can be now applied at once.
* Fixed editing BMP images.  
After editing a BMP image and saving changes, the produced images were broken which made them unusable. The issue has been fixed and BPM images are now saved properly.
* Improved the behavior of the image save modal on lower screen resolutions.  
The modal displayed when saving the edited image was not responsive which made parts of its content not accessible. A scrollbar has been introduced to make it possible to navigate if the viewport height is limited.
* Improved the validation of tags defined for assets.  
If a long tag has been defined for an asset, it resulted in an error response returned from the server. From now on, the length of tags is validated on the frontend side.
* Fixed asset selection issues on Safari.  
When clicking and holding the left mouse button to select multiple files, the selection box acted unexpectedly at a certain point.
* Fixed issues related to using multiple CKBox instances on one web page.  
In some cases, multiple CKBox instances on a web page interfered with each other due to the CKBox internal cache not being properly separated. Additional cache separation has been introduced to ensure that instances with different [id](#ckbox/latest/guides/configuration/configuration-options.html--id) don’t affect each other.
* Fixed text overflow issues in the filename conflict resolution modal displayed for copy or move operation.
* Fixed styling of the `dark` theme.

<a id="ckbox/latest/guides/changelog.html--breaking-changes">

#### Breaking changes

* Removed the `assetsOrigin` option.  
Previously, CKBox used the `assetOrigin` option to assemble the URLs to asset files served through the CDN. This configuration option became obsolete after introducing the `url` and `imageUrls` attributes in the [asset model](https://api.ckbox.io/api/docs#tag/Assets/operation/getAsset) of the CKBox REST API. From now all the required URLs can be obtained from the REST API responses.
* Removed `navy` and `aqua` themes.  
The set of built-in themes has been reduced and CKBox currently provides only the default and the `dark` themes.
* Removed `getUrl()` and `getResponsiveImageUrl()` methods from the asset objects passed to the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback.  
Both methods become obsolete after introducing the `url` and `imageUrls` attributes in the [asset model](https://api.ckbox.io/api/docs#tag/Assets/operation/getAsset) of the CKBox REST API. URLs to different image formats for the purpose of [image conversion](#ckbox/latest/features/images/conversion.html) can be assembled manually using the [CKBox REST API](https://api.ckbox.io/api/docs#tag/Assets/operation/getImageHandler).
* Simplified `language` configuration option.  
Previously it was possible to enter debugging mode for translations by passing an undocumented object with following shape: `{ ui: string; debug?: boolean }`. This possibility has been removed and from now on it’s only possible to pass a language code.
* Deprecated top-level `openLastView`, `startupCategoryId`, and `startupFolderId` configuration options.  
From now on they are available on `view` config option, e.g. `view.openLastView`. Their top-level counterparts will continue to work until the next major version of CKBox.

<a id="ckbox/latest/guides/changelog.html--160-12072023">

### 1.6.0 (12.07.2023)

<a id="ckbox/latest/guides/changelog.html--features-12">

#### Features

* Introduced [Image Editing](#ckbox/latest/features/images/editing/editing.html) feature.  
A newly added image editing feature enables users to perform basic operations on the image files. These operations include:

  * Cropping: Users can select a specific portion of an image, helping them focus on a particular subject.
  * Rotating: Users can rotate an image by 90 degrees clockwise or counterclockwise.
  * Flipping: Users can mirror an image horizontally or vertically.
  * Resizing: Users can change the dimensions of an image (width and height) by specifying custom dimensions.  
After editing an image, users have the option to save it as a new asset or overwrite the edited image file.
* Introduced [Workspaces](#ckbox/latest/features/file-management/workspaces.html) feature  
Workspaces provide a convenient solution for achieving data isolation and user segregation within CKBox. They allow to easily separate storage and data spaces, giving a precise control over assigning specific users, user groups, or tenants to each workspace. This allows to maintain distinct data and storage spaces, ensuring data separation and seamless integration into multi-tenant applications.
* Introduced a mechanism allowing to quickly locate the uploaded file.  
Implemented a mechanism to improve the process of finding newly uploaded files within the asset list. It was sometimes difficult to find the files after upload. A _Go to file_ button has been added next to the uploaded file’s name in the upload modal. The button becomes visible when hovering over the file entry, allowing users to quickly locate the file within CKBox. By clicking the _Go to file_ button, the corresponding file is highlighted and the focus automatically moves to it.
* Unified display of location identifiers.  
Categories and folders identifiers visible to the administrators are now displayed in a more consistent way. The new identifier label now enables administrators to copy its value to the clipboard by simply clicking on it.
* Added text wrapping in file descriptions.  
Previously, file descriptions were restricted to a single line, making it difficult to view the entire content when a long file description was defined for an asset. Now, file descriptions are presented in a multiline input that wraps the text, enabling the full description to be immediately visible.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-15">

#### Bug fixes

* Improved loading of image thumbnails.  
The frontend is now aware of the image processing state, enabling the automatic refreshing of thumbnails when necessary. This ensures that users always have up-to-date and accurate representations of their images. Additionally, thumbnails for broken images are not unnecessarily refetched.
* UI improvements.  
CKBox user interface is constantly improved, and this release brings some fixes to the UI, such as: removing unnecessary animations for slider component, improving the loading placeholders inside the admin section, and more.

<a id="ckbox/latest/guides/changelog.html--151-25052023">

### 1.5.1 (25.05.2023)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-16">

#### Bug fixes

* Fixed behavior of asset properties drawer in `Recent` category.  
In the previous version, when navigating between assets in `Recent` category with open properties drawer, some asset properties were not being updated properly.

<a id="ckbox/latest/guides/changelog.html--150-09052023">

### 1.5.0 (09.05.2023)

<a id="ckbox/latest/guides/changelog.html--features-13">

#### Features

* Introduced keyboard support for the _Move_ and _Copy_ operations.  
It is now possible to use well-known keyboard shortcuts to copy and move files between locations:  
  * To copy files, use Ctrl+C \- Ctrl+V (or Cmd+C \- Cmd+V on Mac).
  * To move files, use Ctrl+X \- Ctrl+V (or Cmd+X \- Cmd+V on Mac).
* Introduced the [openLastView](#ckbox/latest/guides/configuration/configuration-options.html--viewopenlastview) option.  
Added a configuration option that allows users to control whether the browser remembers the last opened folder and automatically reopens it after refreshing the page. This option is enabled by default so the last location is remembered.
* Introduced the [startupCategoryId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupcategoryid) and [startupFolderId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupfolderid) options.  
Added two new options, [startupCategoryId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupcategoryid) and [startupFolderId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupfolderid), allowing to control which location is opened immediately after CKBox starts. When used in combination with the [openLastView](#ckbox/latest/guides/configuration/configuration-options.html--viewopenlastview) option set to `false`, so that the last user location is not remembered, CKBox can now always start in the predefined location.
* The properties panel now shows the ID of the folder or category.  
This allows admin users to conveniently check the ID of the folder or category, which is required by some CKBox configuration options passed through JavaScript.
* Added a loader indicating the loading state in the conflict resolution dialog.  
When a file with the same name exists in the target directory, a dialog appears, allowing the user to choose an operation: override, skip, or change the name of the copied or moved file. This operation may not be instanteous, so a loader is displayed in the modal to provide visual feedback to the user about the ongoing operation.
* Improved the consistency of paddings in the gallery component.
* Updated third-party dependencies.  
Upgraded the versions of the third-party libraries to ensure the security and stability of all the dependencies used by CKBox.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-17">

#### Bug fixes

* File uploads no longer stop if the browser tab is moved to the background.  
In the previous versions of CKBox, if a user started uploading a large number of files and moved the browser tab to the background the upload process unexpectedly stopped until the tab was active again at which point it resumed. This issue has been resolved and the upload queue is now processed without any delays even if the tab remains in the background.
* Fixed category allowed extensions validation after changes to admin settings.  
Previously, extensions validated at the frontend did not immediately recognize changes made in the administration panel. This sometimes caused file extensions to be falsely marked as disallowed during attempts to move or copy files.

<a id="ckbox/latest/guides/changelog.html--140-12042023">

### 1.4.0 (12.04.2023)

<a id="ckbox/latest/guides/changelog.html--features-14">

#### Features

* Introduced ability to copy and move assets.  
CKBox users can now copy and move assets between folders and asset categories. A new workflow improvement has been added for cases where a file with the same name already exists in the target location. Users will be prompted to choose between overriding, renaming, or skipping the file.
* Added folder upload feature.  
CKBox now allows users to upload folders with subfolders and files directly using the dedicated _Folder upload_ button or by dragging and dropping the folder into the CKBox workspace area. Empty folders will be ignored during the upload process.
* Introduced a new icon set.  
CKBox has been updated with a new set of icons based on, or inspired by, the [Material Icons](https://mui.com/material-ui/material-icons/) set.
* Introduced new modal dialogs.  
A consistent visual style has been implemented for modal dialogs throughout the application.
* Introduced loading state for opened folders.  
Folders with expanding content now show a loader next to the folder name, indicating that the folder contents are loading, even on slower connections. A consistent skeleton loader has been added for folder content loading, providing a better user experience on slower connections.
* Introduced transitions and animations of the user interface.  
New animations and transitions have been added to various parts of the user interface, improving its fluidity and visual feedback.
* User interface improvements.  
  * Popup menus will now close upon pressing the Esc key.
  * Default focus outlines have been removed.
  * Navigation buttons padding has been adjusted.
  * The look of icons in file view mode for non-image files has been changed.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-18">

#### Bug fixes

* Improved specificity of CKBox’s CSS rules.  
The fixed style reset ensures that the internal CKBox styling is not unintentionally overridden by the styles of the embedding application.
* Fixed issue with saving asset metadata in preview mode.  
Previously, changes made to file metadata in preview mode were not saved if the properties panel had been opened in the main CKBox view. This issue has been resolved.

<a id="ckbox/latest/guides/changelog.html--132-21022023">

### 1.3.2 (21.02.2023)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-19">

#### Bug fixes

* Changed breakpoint for fixed components.  
Breakpoint for fixed components was adjusted to use a boundary value of `900px`. That will allow some components to use overlay mode on lower CKBox window widths. That should improve the overall UX.

<a id="ckbox/latest/guides/changelog.html--131-15022023">

### 1.3.1 (15.02.2023)

<a id="ckbox/latest/guides/changelog.html--bug-fixes-20">

#### Bug fixes

* Fixed notifications on missing resources.  
The notification system was improved to stop spawning notifications on a missing resource (category or folder). The notification did not provide any valuable information and only distracted the user.

<a id="ckbox/latest/guides/changelog.html--130-06022023">

### 1.3.0 (06.02.2023)

<a id="ckbox/latest/guides/changelog.html--features-15">

#### Features

* Introduced folders feature.  
It is now possible to organize assets into folders under each of the asset categories. All the existing user assets remained in the top-level categories.
* Introduced new default light theme.  
_Light_ is the new default theme of CKBox. The previous theme is still available under the name `navy`.
* Improvements in search.  
Clicking on the recent search entry now immediately applies the search. Keyboard support in the search form has been improved too, so it is now possible to submit the search form using Enter.
* Added file properties drawer in the asset preview mode.  
File properties in the preview mode are currently displayed the same way as in the assets view, using the collapsible drawer on the right side of the screen.
* Improvements to the properties drawer.  
Properties drawer can now be closed using the Esc key. Additionally, the asset preview inside the drawer now respects the _Keep aspect ratio_ option set in the _Display options_ menu.
* The user can now easily access the location of the asset from the search result view. Asset properties now display the location of the file as an active link directing to the folder or category to which the asset belongs.
* Added keyboard navigation support in the categories and folder tree.
* The asset preview mode can now be closed by clicking on the overlay.
* Added a default border around CKBox element.  
When CKBox in the [inline mode](#ckbox/latest/examples/display/inline-mode.html) is embedded on a web page, it has a default border to make to component boundaries visible.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-21">

#### Bug fixes

* Fixed issue that sometimes caused the asset disappear from the search results after its properties have been edited.
* Fixed focus issues in modals.  
In some cases, after closing the modal, focus has been not returned properly to the required element. Now focus is properly returned to the element that invoked the action that displayed the modal.

<a id="ckbox/latest/guides/changelog.html--121-28112022">

### 1.2.1 (28.11.2022)

<a id="ckbox/latest/guides/changelog.html--features-16">

#### Features

* Introduced keyboard support for the _Search_ feature.  
It is now possible to open the search window using standard keyboard shortcuts: Ctrl+F or Cmd+F.
* Search results are now remembered between web page reloads until intentionally closed by the user.
* Introduced sorting of the assets in the search results view.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-22">

#### Bug fixes

* Fixed an issue that caused duplicated upload file requests.  
In some circumstances, CKBox sent double HTTP requests with uploaded files. Usually, these unnecessary requests were canceled, but sometimes it resulted in files being uploaded twice into CKBox.
* Upload progress is no longer visible if the image resolution exceeds the limits.  
The progress bar of the image was unnecessarily visible if the image resolution exceeded the allowed limits.
* Fixed stacking of the file preview.  
In some cases, file preview might have been overlapped by elements on the host application. CSS rules of the file preview container have been changed to minimize this possibility.
* Fixed duplicated entries on the list of recent searches.
* Removed misleading placeholder in the `Tags` field in the advanced search mode.  
The placeholder displayed in the tag input component is no longer visible if there are any elements present in the input.
* Fixed issue with saving file properties when all tags were removed.  
In case the file had any tags defined, it was impossible to remove all the tags and save the file properties. This action resulted in an unexpected server error.
* The `Save` button in file properties section is no longer active if there are no changes to save.
* Improved formatting of the tooltip displaying the details of search entries on the list of recent searches.
* Fixed styling of the slider in the images configuration inside the administration panel.
* Introduced ellipsis for long search queries that did not fit in the list element on the list of recent searches.
* Introduced ellipsis for long category names that did not fit inside the container on the list of categories in the administration panel.

<a id="ckbox/latest/guides/changelog.html--120-16112022">

### 1.2.0 (16.11.2022)

<a id="ckbox/latest/guides/changelog.html--features-17">

#### Features

* Introduced the _Search_ feature.  
CKBox will now allow searching the assets by phrase, and / or by custom filters such as: `tags`, `categories`, `extensions`, `upload date` and `last modification date`
* Introduced the _assets tagging_ feature.  
Assets can now be tagged for a better user-personalization. Tags can be used for searching the assets by tag name.
* Introduced the assets preview feature.  
CKBox introduces the full-screen preview of the asset image. This will allow for inspecting the asset in more detail.
* Introduced the drawer component.  
The drawer component will now display asset properties in a more contextual form. The drawer will expand from the right side of the interface giving the user quick insight into the asset’s metadata.
* Introduced the checkbox assets selection mechanism.  
The assets can now be selected using a checkbox button on the asset tile.
* Added plan limits validation before uploading the file.  
CKBox now validates the plan limits applied to a given subscription to prevent uploading too large files. The upload doesn’t start if the file exceeds the size, or megapixels limit. The user is notified with the right context message.
* Added the loading state to the button component.  
The button component now has a new `loading` state. That is used in various interface places to give the best visual feedback for async actions.
* Added the upload dialog animation on minimize / maximize.  
The upload dialog is now animated while minimizing or maximizing.
* Improved the accessibility of dialogs.
* Introduced active state to the buttons.  
Buttons can now hold an `active` state that allows creating a toggle button.
* Introduced the “Powered by CKBox” credit link.  
The free plan subscription will now have a “Powered by CKBox” credit link visible at the bottom of the navigation panel. That is only a thing of the personal plan, and neither the Starter, Premium, or Pro plans have this link.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-23">

#### Bug fixes

* Fixed bugs related to file selection.  
Asset checkboxes now use different stacking contexts to prevent issues and conflicts with the mouse and keyboard selection.
* Introduced minor fixes for navigation panel.  
Some layout fixes regarding the navigation panel have been introduced. Those include preventing the resized handle from slipping and adjusting the styling.
* Fixed the behaviour of the toolbar.  
These fixes include adjusting the padding of the action items, disabling label wrapping for buttons, and fixing the behavior of the elements during navigation bar resize.
* Fixed minor issues in the upload dialog.  
Previous upload dialog size could cause problems in different language versions. The dimensions of the upload dialog are now larger, and the overall UX of that component has been improved.
* Fixed issue related to thumbnails alignement.
* Improved asset selection mechanism using mouse area selection, and keyboard selection.  
The mouse and keyboard events handling has been improved and integrated with the new checkbox selection feature.
* Fixed stacking context of resize handles.
* Fixed rendering issues in React SSR sample.  
The React SSR (Next.js) integration sample now uses different Webpack configuration to prevent the splitting of `@ckbox` packages into separate cache groups.
* Fixed broken links in end-user docs.

<a id="ckbox/latest/guides/changelog.html--110-13072022">

### 1.1.0 (13.07.2022)

<a id="ckbox/latest/guides/changelog.html--features-18">

#### Features

* Users of commercial plans now have access to the REST API.
* CKBox now displays a more verbose error when the token validation fails on the backend side.
* Assets can now be quickly chosen by double-clicking on the asset thumbnail.
* CKBox now supports keyboard shortcut mapping for deleting assets compatible with macOS. It’s possible to delete assets using Delete or ⌘ \+ Backspace.
* CKBox version is now available from the global `CKBox` object via `CKBox.version`.
* Added JWT token lifespan calculation based on the `exp` field.  
If the `exp` field is present in the JWT token obtained from the `tokenUrl`, CKBox will refresh the token only if it’s about to expire.
* CKBox now validates application configuration and fails fast if `serviceOrigin` is provided in a wrong format.

<a id="ckbox/latest/guides/changelog.html--bug-fixes-24">

#### Bug fixes

* Fixed style cascading from the host application.  
The fixed style reset now prevents a situation when the host app may influence internal CKBox styling by unintentional CSS overrides.
* Fixed limits in Personal plan.  
After exceeding the storage limit of the Personal plan, it is no longer possible to upload any new files. After exceeding the bandwidth limit, files will no longer be served from the CDN.
* Fixed counting the bandwidth.  
The used service bandwidth was not counted properly and in some cases, it remained at 0.
* Fixed initial dialog dimensions if they become invalid in the current viewport.  
Previously, CKBox didn’t check if the dialog became unusable due to viewport changes. This could lead to situations when the lastly saved display settings (size, position) of the CKBox dialog become invalid due to incompatibility with the current viewport e.g. dialog outside the visible viewport.
* Fixed the default navigation when opening the CKBox.  
Previously when the CKBox was opened for the first time, the first category on top was the `Recent` category. Now CKBox is opened with the first user-defined category.
* Fixed dialog header styling issue.  
Only the upload dialog uses a thicker header now.
* Using icons instead of text in translation-sensitive UI parts.  
In order to make the upload dialog look better in languages where “Abort upload” translates to a long string, we now use icon instead of text.
* Fixed missing default categories in 30-day trials.  
Website environments created for 30-day trials did not have the default categories (Files, Documents, Images) created at the start.
* `col-resize` cursor is displayed all the time while resizing the navigation bar.
* Fixed missing translation key warning for asset deletion dialog.

<a id="ckbox/latest/guides/configuration/authentication.html">source file: "ckbox/latest/guides/configuration/authentication.html"</a>

## Authentication

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the [Customer Portal](https://portal.ckeditor.com). CKBox is a commercial product and in order to use it, you need to [obtain a license](https://ckeditor.com/pricing/#plan-ckbox). The access credentials required to configure the `tokenUrl` can be found in the [Customer Portal](https://portal.ckeditor.com).

<a id="ckbox/latest/guides/configuration/authentication.html--creating-access-credentials">

### Creating access credentials

To obtain the access credentials required to create the token endpoint, please log in to the [Customer Portal](https://portal.ckeditor.com/login). Then navigate to “Cloud environments”.

<a id="ckbox/latest/guides/configuration/authentication.html--website-environment">

#### Website environment

To obtain access credentials, first, you have to choose the environment. Environments are independent spaces for your data, and you can create any number of them. From the list of environments select the one that you want to manage or create a new one.

<a id="ckbox/latest/guides/configuration/authentication.html--access-credentials">

#### Access credentials

Next, go to the “Access credentials” tab and click the “Create a new access key” button.

The modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

For your safety, the access key value is partially obscured. You can copy the key value with the `Copy` icon next to the key.

Here you can also see the environment ID required to validate your istallation. It is located in the top right corner of the Cloud environments pane.

To read more about the concept of environments, please refer to the [Environments management](https://ckeditor.com/docs/cs/latest/guides/environments-management.html) article.

<a id="ckbox/latest/guides/configuration/authentication.html--token-endpoint">

### Token endpoint

With the environment and access credentials ready, you can create a [security token endpoint](https://ckeditor.com/docs/cs/latest/guides/security/token-endpoint.html). The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

Below are implementation examples in various languages:

* [ASP.NET](#cs/latest/examples/token-endpoints/dotnet.html)
* [Java](#cs/latest/examples/token-endpoints/java.html)
* [Node.js](#cs/latest/examples/token-endpoints/nodejs.html)
* [PHP](#cs/latest/examples/token-endpoints/php.html)
* [Python](#cs/latest/examples/token-endpoints/python.html)

We highly recommend using the libraries listed on jwt.io to create the token.  
If you encounter problems creating the token endpoint in another server-side language, or if you have any other suggestions regarding the documentation, please contact us.

<a id="ckbox/latest/guides/configuration/authentication.html--development-token-endpoint">

#### Development token endpoint

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in a few simple steps:

From the list of environments select the one that you want to manage or create a new one.

After choosing the environment, the development token URL will show up at the bottom of the “CKEditor configuration” section:

<a id="ckbox/latest/guides/configuration/authentication.html--token-payload">

### Token payload

**Payload properties**

The following properties **must** be included in the JWT token payload:

* `aud` – The environment ID, which is the identifier of the environment created in the [Customer Portal](https://portal.ckeditor.com).
* `sub` – The user ID, which is the unique identifier of the user for whom the token is issued.
* `iat` – A timestamp the token was **issued at**. Make sure that `iat` is present and contains the correct time stated in seconds. Some JWT implementations do not include it by default. Additionally, the system time may be invalid, causing strange issues with tokens (see, for example, [Docker for Mac time drift](https://github.com/docker/for-mac/issues/2076)).
* `auth` – An object defining the user’s role. Allowed values are `user` for regular users and `admin` for administrator users.

The payload example below will enable access to CKBox as administrator:

```
{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "example-user-id",
    "auth": {
        "ckbox": {
            "role": "admin"
        }
    }
}

```

<a id="ckbox/latest/guides/configuration/authentication.html--user-roles">

#### User roles

CKBox users are divided into two groups: regular users and administrators. Regular users can use all the features of the application allowing for file management (uploading, renaming, removing, etc.). Administrators additionally have access to the [administration management panel](#ckbox/latest/features/administration-panel.html), which allows configuring various aspects of the CKBox environment, like the available categories, their allowed extensions, and the quality of responsive images.

The user role is defined by setting an appropriate value in the `auth.ckbox.role` field of the token payload:

* if you want the user to be an administrator, set `auth.ckbox.role` to `admin`  
```  
"auth": {  
    "ckbox": {  
        "role": "admin"  
    }  
}  
```
* for the regular user, `auth.ckbox.role` should be set to `user`  
```  
"auth": {  
    "ckbox": {  
        "role": "user"  
    }  
}  
```

The premium [permissions](#ckbox/latest/features/permissions.html) feature lets the integrator assign permissions to regular users. It allows greater control over access and asset management rights.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html">source file: "ckbox/latest/guides/configuration/ckeditor-integration.html"</a>

## CKEditor 5 integration

CKBox can be easily added to CKEditr 5 as a full-fledged asset manager. In this guide, we will focus on the simplest integration scenario, where both CKEditor 5 and CKBox are added to the web page using links from the CDN.

To enable CKBox in your CKEditor 5 instance, add the CDN script and all the required configuration options to the object under the `ckbox` key. In the simplest scenario, CKBox requires only the `tokenUrl` option.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--quick-example">

### Quick example

For the purpose of this example, we will use the classic editor type, but there is more editor types to choose from! You can learn more about running CKEditor 5 from the CDN from [a dedicated guide](#ckeditor5/latest/getting-started/installation/cloud/quick-start.html--installing-ckeditor-5-from-cdn) in the CKEditor 5 documentation.

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/lark.css">
    </head>
    <body>
        <div id="editor"></div>
        <script>
            const {
                ClassicEditor,
                Essentials,
                CKBox,
                CKBoxImageEdit,
                PictureEditing,
                ImageUpload,
                Heading,
                Bold,
                Italic,
                BlockQuote,
                Indent,
                Link,
                List
            } = CKEDITOR;

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    plugins: [
                        Essentials, CKBox, CKBoxImageEdit, ImageUpload,
                        Heading, Bold, Italic, BlockQuote, Indent,
                        Link, List, PictureEditing
                    ],
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'lark'
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

The demo sample below presents the result of this integration. Try pasting images from the clipboard directly into the editing area as well as dropping images — the files will be saved on the fly by CKBox.

You can use the toolbar button to open the CKBox dialog window. There you can manage your files or choose an asset that should be added to the edited content. The image embedded in the editor this way will produce a highly optimized `<picture>` tag. If the image has a description set in its properties in CKBox, the description will be automatically used as an `alt` attribute of the image embedded in the editor.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--configuration-options">

### Configuration options

Using the `ckbox` attribute, you can pass any of the available [configuration options](#ckbox/latest/guides/configuration/configuration-options.html) to a CKBox instance.

As an example, let’s run both CKEditor 5 and CKBox in Spanish, and additionally let’s set the theme of CKBox to `dark`.

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5/translations/es.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />

        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/translations/es.js"></script>
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/dark.css">
    </head>
    <body>
        <div id="editor"></div>

        <script src="https://cdn.ckeditor.com/ckeditor5/2.11.1/ckeditor5.umd.js"></script>

        <script type="module">
            const {
                ClassicEditor,
                Essentials,
                CKBox,
                CKBoxImageEdit,
                ImageUpload,
                Heading,
                Bold,
                Italic,
                BlockQuote,
                Indent,
                Link,
                List
            } = CKEDITOR;

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    language: 'es',
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'dark'
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

As you can see in the example above, the `language` option for CKBox was omitted. This was intentional because by default, the language of CKBox will match the language of CKEditor 5, which has been already set to Spanish. Setting language again in `ckbox.language` would be superfluous in this case.

Below you can see a live example of the configuration presented above.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--plugin-specific-options">

#### Plugin-specific options

CKEditor 5 plugin for CKBox exposes two plugin-specific options. These options are used to configure the plugin and are not passed down to the CKBox instance.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--defaultuploadcategories">

##### `defaultUploadCategories`

When uploading the asset to CKBox by dropping or pasting it into the editor area, the asset by default lands into the first category that allows the asset extension. There might be cases where you would like to have more control over this, e.g. when two or more categories are configured to allow for the same file extension (please refer to the [Category management](#ckbox/latest/features/administration-panel.html--category-management) guide to read more about category configuration options in the administration panel). The `defaultUploadCategories` option allows to explicitly define categories that should be used to upload the particular extensions.

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            defaultUploadCategories: {
                // Category referenced by name
                Files: ['pdf', 'txt', 'zip'],
                // Category referenced by ID
                'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': ['jpg', 'png']
            }
        }
    } )
    .catch( error => {
        console.error( error );
    } );

```

As you can see in the example above, the category can be referenced either by its name or by ID. When referencing the category by its name, you will have to update this configuration if the category name is changed. Referencing the category by ID is a more bulletproof solution because the category ID always remains the same. The category ID can be found in the [_Asset categories_ section](#ckbox/latest/features/administration-panel.html--category-management) of the administration panel.

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--ignoredataid">

##### `ignoreDataId`

When assets are inserted into the editor content, the CKBox plugin for CKEditor will by default add a `data-ckbox-resource-id`. The purpose of this tag is to bind the content to the CKBox asset and allow for basic asset usage tracking (i.e. checking which CKBox assets are used in your content).

For example:

```
<a href="..." data-ckbox-resource-id="hAza1FIb2YIV">link</a>

```

If you want to disable this feature, please set the `ignoreDataId` option to `true`.

```
ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            ignoreDataId: true
        }
    } )
    .catch( error => {
        console.error( error );
    } );

```

<a id="ckbox/latest/guides/configuration/ckeditor-integration.html--advanced-integration">

### Advanced integration

To read about more advanced integration scenarios, please refer to the [CKBox file manager](https://ckeditor.com/docs/ckeditor5/latest/features/images/image-upload/ckbox.html) article in the CKEditor 5 documentation.

<a id="ckbox/latest/guides/configuration/configuration-options.html">source file: "ckbox/latest/guides/configuration/configuration-options.html"</a>

## Configuration options

When creating a CKBox instance, it is possible to pass various configuration options. Some of them are mandatory, while others allow customizing the component. Below, you can find the list of all available configuration options with live usage examples.

<a id="ckbox/latest/guides/configuration/configuration-options.html--ckbox-mounting-modes">

### CKBox mounting modes

CKBox can be mounted as either a full application or as a standalone image editor. In the latter mode, its capabilities are restricted to image editing only.

In order to initialize an instance of CKBox, regardless of the mode, a DOM node must be passed along with an object containing configuration options:

```
// Full application
CKBox.mount(domNode, config);

// Standalone image editor
CKBox.mountImageEditor(domNode, config);

```

There is a list of configuration options common for both modes. In addition, each mode has its own specific options. Read about each group in the paragraphs below.

<a id="ckbox/latest/guides/configuration/configuration-options.html--list-of-common-configuration-options">

### List of common configuration options

The table below presents a list of the available configuration options common for both full application and standalone image editor. Please click the option name to read about details and see a live usage example.

| Option name                                                                                                              | Description                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [tokenUrl](#ckbox/latest/guides/configuration/configuration-options.html--tokenurl)                                      | The URL of the [token endpoint](#ckbox/latest/guides/configuration/authentication.html--token-endpoint) or a callback that provides the token. This option is mandatory. |
| [language](#ckbox/latest/guides/configuration/configuration-options.html--language)                                      | The user interface language localization to use.                                                                                                                         |
| [theme](#ckbox/latest/guides/configuration/configuration-options.html--theme)                                            | Theme of the user interface.                                                                                                                                             |
| [id](#ckbox/latest/guides/configuration/configuration-options.html--id)                                                  | Sets the instance ID.                                                                                                                                                    |
| [serviceOrigin](#ckbox/latest/guides/configuration/configuration-options.html--serviceorigin)                            | Sets the origin to use for the REST API.                                                                                                                                 |
| [choosableFileExtensions](#ckbox/latest/guides/configuration/configuration-options.html--choosablefileextensions)        | Controls which extensions are allowed to be choosed.                                                                                                                     |
| [imageEditing.allowOverwrite](#ckbox/latest/guides/configuration/configuration-options.html--imageeditingallowoverwrite) | Whether to show file overwrite checkbox in image editor.                                                                                                                 |

<a id="ckbox/latest/guides/configuration/configuration-options.html--tokenurl">

#### `tokenUrl`

As you might have read in the [Authentication](#ckbox/latest/guides/configuration/authentication.html) guide, CKBox uses JWT tokens for authentication. These tokens must be somehow obtained by the CKBox frontend client, and this is where the `tokenUrl` option comes into place. Using the URL passed here, CKBox obtains the JWT token and attaches it to all the API HTTP requests that require authentication.

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url'
});

```

Alternatively, a callback that returns a promisified token can be used:

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: () =>
        new Promise((resolve, reject) => {
            const xhr = new XMLHttpRequest();

            xhr.open('GET', 'https://your.token.url');

            xhr.addEventListener('load', () => {
                const statusCode = xhr.status;
                const xhrResponse = xhr.response;

                if (statusCode < 200 || statusCode > 299) {
                    return reject(new Error('Cannot download new token!'));
                }

                return resolve(xhrResponse);
            });

            xhr.addEventListener('error', () => reject(new Error('Network Error')));
            xhr.addEventListener('abort', () => reject(new Error('Abort')));

            xhr.send();
        }),
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--language">

#### `language`

Configures the language to use in the CKBox instance. Please note that if you want to use a language other than English, you must include the appropriate language resource on your webpage:

```
<script src="https://cdn.ckbox.io/ckbox/2.11.1/translations/es.js"></script>

```

To read more about the supported languages, please refer to the [Localization](#ckbox/latest/guides/configuration/localization.html) guide.

In the example below, CKBox is configured to use Spanish.

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    language: 'es'
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--theme">

#### `theme`

Configures theme to use.

To read more about theming options available in CKBox, please refer to [Theming](#ckbox/latest/guides/configuration/theming.html) guide.

In the example below, CKBox is configured to use the `dark` theme.

```
<link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/dark.css">

```

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    theme: 'dark'
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--id">

#### `id`

Sets the instance ID. This option is useful if you have multiple instances of CKBox on your webpage. By default, all the instances will share some parts of the data, e.g. user display options stored in the browser’s local storage. If CKBox instances have different `id`\-s assigned, their user display options will be stored separately.

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    id: 'instance1'
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--serviceorigin">

#### `serviceOrigin`

Sets the origin to use for the REST API if CKBox backend is an own-hosted on-premises installation.

```
// Or `CKBox.mountImageEditor( ... )`
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    serviceOrigin: 'https://api.example.com'
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--choosablefileextensions">

#### `choosableFileExtensions`

Specifies the file extensions considered valid for user interaction. Whith this option developers can restrict user interaction to only those assets whose file extensions match those listed in the array. Assets whose file extensions are not listed in the `choosableFileExtensions` array are automatically disabled within the CKBox interface.

```
CKBox.mount(document.querySelector('#ckbox'), {
    choosableFileExtensions: ['jpg', 'png']
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--imageeditingallowoverwrite">

#### `imageEditing.allowOverwrite`

Sets whether to show the ‘Overwrite file’ checkbox in image editor.  
By default, the option is shown.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    imageEditing: {
        allowOverwrite: false,
    },
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--list-of-configuration-options-full-app">

### List of configuration options (full app)

The table below presents a compact list of the available configuration options specific for CKBox mounted as a full application. Please click the option name to read about details and see a live usage example.

| Option name                                                                                                                | Description                                                                     |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [dialog](#ckbox/latest/guides/configuration/configuration-options.html--dialog)                                            | Defines whether the CKBox instance should open in dialog mode.                  |
| [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose)                           | The callback executed after choosing files.                                     |
| [categories.icons](#ckbox/latest/guides/configuration/configuration-options.html--categoriesicons)                         | Allows setting custom icons for categories.                                     |
| [view.openLastView](#ckbox/latest/guides/configuration/configuration-options.html--viewopenlastview)                       | Sets if the last view visited by the user will be reopened on the next startup. |
| [view.onChange](#ckbox/latest/guides/configuration/configuration-options.html--viewonchange)                               | Callback executed when view is changed.                                         |
| [view.startupFolderId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupfolderid)                 | Sets the ID of the folder that will be opened on startup.                       |
| [view.startupCategoryId](#ckbox/latest/guides/configuration/configuration-options.html--viewstartupcategoryid)             | Sets the ID of the category that will be opened on startup.                     |
| [upload.componentsHideTimeout](#ckbox/latest/guides/configuration/configuration-options.html--uploadcomponentshidetimeout) | Sets timeout after which upload components are hidden after completed upload.   |
| [upload.dialogMinimizeTimeout](#ckbox/latest/guides/configuration/configuration-options.html--uploaddialogminimizetimeout) | Sets timeout after which upload dialog is minimized after completed upload.     |

<a id="ckbox/latest/guides/configuration/configuration-options.html--dialog">

#### `dialog`

This option allows opening CKBox in dialog mode. It takes a boolean value or a configuration object with the following attributes:

| Attribute | Description                                 |
| --------- | ------------------------------------------- |
| width     | Dialog width in pixels.                     |
| height    | Dialog height in pixels.                    |
| onClose   | Callback executed after closing the dialog. |

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    dialog: {
        width: 800,
        height: 600,
        onClose: () => {
            console.log('Dialog closed!')
        }
    },
});

```

Click on the button below to open CKBox in dialog mode.

<a id="ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose">

#### `assets.onChoose`

Defines a callback executed after choosing files. If this option is defined, the `Choose` button will be visible in CKBox. After selecting assets and clicking the `Choose` button, a callback defined in `assets.onChoose` will receive an array of objects representing chosen assets.

Each asset object contains a `data` property with the following information about the asset:

| Attribute  | Description                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| id         | Asset id.                                                                                                                                |
| name       | Asset file name.                                                                                                                         |
| extension  | Asset file extension.                                                                                                                    |
| imageUrls  | Maps available image widths to respective URLs on CDN. Useful for creating responsive images.                                            |
| categoryId | Category ID the asset belongs to.                                                                                                        |
| size       | Asset file size in bytes.                                                                                                                |
| uploadedAt | Date the asset has been uploaded.                                                                                                        |
| metadata   | Metadata of the asset. This object is format specific, i.e. for images it contains information about picture width and height in pixels. |
| url        | URL to original file on CDN.                                                                                                             |

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    assets: {
        // Callback executed after choosing assets
        onChoose: (assets) => {
            assets.forEach(({ data }) => {
                console.log(data);
            })
        }
    }
});

```

Click the button below to open CKBox in the dialog mode. URLs of the chosen files will be logged in the console.

<a id="ckbox/latest/guides/configuration/configuration-options.html--categoriesicons">

#### `categories.icons`

Allows setting custom icons for categories. This option takes an object with categories and icons that should be used instead of the default ones.  
Categories can be defined using either their name or `id` (the `id` of the category can be obtained in the [administration panel](#ckbox/latest/features/administration-panel.html)). Icons should be defined as strings containing the SVG images, or as React components.

The category can be referenced either by its name or by ID. When referencing the category by its name, you will have to update this configuration if the category name is changed. Referencing the category by ID is a more bulletproof solution because the category ID remains always the same. The category ID can be found in the [_Asset categories_ section](#ckbox/latest/features/administration-panel.html--category-management) of the administration panel.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    categories: {
        icons: {
            Images: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M12.395 2.553a1 1 0 00-1.45-.385c-.345.23-.614.558-.822.88-.214.33-.403.713-.57 1.116-.334.804-.614 1.768-.84 2.734a31.365 31.365 0 00-.613 3.58 2.64 2.64 0 01-.945-1.067c-.328-.68-.398-1.534-.398-2.654A1 1 0 005.05 6.05 6.981 6.981 0 003 11a7 7 0 1011.95-4.95c-.592-.591-.98-.985-1.348-1.467-.363-.476-.724-1.063-1.207-2.03zM12.12 15.12A3 3 0 017 13s.879.5 2.5.5c0-1 .5-4 1.25-4.5.5 1 .786 1.293 1.371 1.879A2.99 2.99 0 0113 13a2.99 2.99 0 01-.879 2.121z" /></svg>',
            // Category can be referenced by ID
            // 'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': '<svg...'
        }
    }
});

```

Click the button below to open the CKBox instance with a fancy flame icon set for the `Images` category.

<a id="ckbox/latest/guides/configuration/configuration-options.html--viewopenlastview">

#### `view.openLastView`

Configures the startup of CKBox.  
If it is set to `false` the last view visited by the user will not be reopened on the next startup.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    view: {
        openLastView: true
    }
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--viewonchange">

#### `view.onChange`

Callback invoked on CKBox startup and on each view change.

The callback will receive object with following properties:

| Attribute | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| type      | View type. One of the following values: category, fallback, folder, recent, search, settings. |
| data      | View data. This property is present only if view type is category or folder.                  |

Category data contains following properties:

| Attribute   | Description                                  |
| ----------- | -------------------------------------------- |
| id          | Unique ID of the category.                   |
| name        | Name of the category.                        |
| assetsCount | Total number of assets in the category.      |
| extensions  | List of allowed extensions for the category. |

Folder data contains following properties:

| Attribute   | Description                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| id          | Unique ID of the folder.                                                    |
| categoryId  | ID of the root category.                                                    |
| parentId    | ID of the parent folder (only present if folder’s parent is also a folder). |
| name        | Name of the folder.                                                         |
| assetsCount | Total number of assets in the category.                                     |

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    view: {
        onChange: (view) => {
            console.log(view.type);

            if (view.type === 'folder' || view.type === 'category') {
                console.log(view.data.id);
            }
        }
    }
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--viewstartupfolderid">

#### `view.startupFolderId`

Sets the ID of the folder that will be opened on startup.  
This option can be paired with setting `view.openLastView` to `false` to enforce CKBox to always open in a given folder at startup.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    view: {
        startupFolderId: 'PpgFC9jQnvzp'
    }
});

```

To get the folder ID click on the label located below the folder-name heading in the folder settings drawer (available for admin users only).  

<a id="ckbox/latest/guides/configuration/configuration-options.html--viewstartupcategoryid">

#### `view.startupCategoryId`

Sets the ID of the category that will be opened on startup.  
This option can be paired with setting `view.openLastView` to `false` to enforce CKBox to always open in a given category at startup.  
If `view.startupCategoryId` is passed along with the `view.startupFolderId` option, CKBox will prioritize opening category view on the startup.

To get the category ID click on the label located below the category-name heading in the category settings drawer (available for admin users only).  

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    view: {
        startupCategoryId: '849beccc-ea74-11ed-a05b-0242ac120003'
    }
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--viewhidemaximizebutton">

#### `view.hideMaximizeButton`

Sets whether to hide the ‘Maximize’ button.  
By default, the button is shown and enabling this option will hide it.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    view: {
        hideMaximizeButton: true,
    },
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--uploadcomponentshidetimeout">

#### `upload.componentsHideTimeout`

Sets timeout (in milliseconds) after which upload components (dialog and indicator) are hidden. By default, these components hide automatically after 10 seconds. Following rules apply:

* If all uploads are completed successfully, the timeout starts immediately.
* If at least one upload was not successful (e.g. it ended with an error or was aborted), the timeout will not start until user minimizes the upload dialog manually.
* If user interacts with the upload dialog in any way, the timeout is cleared. Once user minimizes the upload dialog manually, the timeout starts again.
* If user opens minimized upload dialog, the timeout is cleared.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    upload: {
        componentsHideTimeout: 5000,
    },
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--uploaddialogminimizetimeout">

#### `upload.dialogMinimizeTimeout`

Sets timeout (in milliseconds) after which upload dialog is minimized once upload is finished and all uploads were successful.  
By default, upload dialog is never minimized automatically.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    upload: {
        dialogMinimizeTimeout: 1000,
    },
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--list-of-configuration-options-standalone-image-editor">

### List of configuration options (standalone image editor)

The table below presents a compact list of the available configuration options specific for CKBox mounted as a standalone image editor. Please click the option name to read about details and see a live usage example.

| Option name                                                                                         | Description                                                                                                                       |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [assetId](#ckbox/latest/guides/configuration/configuration-options.html--assetid)                   | Specifies ID of an image asset to edit. This option is mandatory unless combination of imageUrl and uploadCategoryId is provided. |
| [imageUrl](#ckbox/latest/guides/configuration/configuration-options.html--imageurl)                 | Specifies URL from which image will be downloaded for editing. This option is mandatory unless assetId is provided.               |
| [uploadCategoryId](#ckbox/latest/guides/configuration/configuration-options.html--uploadcategoryid) | Specifies URL from which image will be downloaded for image editing. This option is mandatory if imageUrl is provided.            |
| [onClose](#ckbox/latest/guides/configuration/configuration-options.html--onclose)                   | Callback invoked upon closing the image editor.                                                                                   |
| [onSave](#ckbox/latest/guides/configuration/configuration-options.html--onsave)                     | Callback invoked upon saving the edited image.                                                                                    |

<a id="ckbox/latest/guides/configuration/configuration-options.html--assetid">

#### `assetId`

Specifies ID of a CKBox image asset to edit. Asset must have an extension supported by image editing feature, i.e. one of the following: `jpg`, `jpeg`, `webp`, `png`, `bmp`, `tiff`, or `gif`. Otherwise asset will not be loaded.

```
CKBox.mountImageEditor(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    assetId: 'h94eW7EQf4Nt'
});

```

Click on the button below to open CKBox as standalone image editor.

<a id="ckbox/latest/guides/configuration/configuration-options.html--imageurl">

#### `imageUrl`

This is an alternative way of loading image into standalone image editor. In contrast to using [assetId](#ckbox/latest/guides/configuration/configuration-options.html--assetid), before being displayed for editing, image will be downloaded from provided `imageUrl` and then uploaded to a CKBox category identified by [uploadCategoryId](#ckbox/latest/guides/configuration/configuration-options.html--uploadcategoryid).

Name of the image uploaded to CKBox will be deduced from URL’s pathname and its extension will be deduced from `Content-Type` response header.

```
CKBox.mountImageEditor(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    imageUrl: 'https://your.files.url/images/my_image',
    uploadCategoryId: 'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b'
});

```

Click on the button below to open CKBox as standalone image editor and edit an external image.

<a id="ckbox/latest/guides/configuration/configuration-options.html--uploadcategoryid">

#### `uploadCategoryId`

This option must be provided along with [imageUrl](#ckbox/latest/guides/configuration/configuration-options.html--imageurl) option. Before being displayed for editing, image located at [imageUrl](#ckbox/latest/guides/configuration/configuration-options.html--imageurl) will be downloaded and then uploaded to a CKBox category identified by `uploadCategoryId`.

<a id="ckbox/latest/guides/configuration/configuration-options.html--onclose">

#### `onClose`

Callback invoked upon closing standalone image editor.

```
CKBox.mountImageEditor(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    assetId: 'h94eW7EQf4Nt',
    onClose: () => {
        console.log('Dialog closed!')
    }
});

```

<a id="ckbox/latest/guides/configuration/configuration-options.html--onsave">

#### `onSave`

Callback invoked once the edited image has been successfully saved. Data of edited asset will be passed to the callback as `data` property containing following info:

| Attribute  | Description                                                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| id         | Asset id.                                                                                                                                |
| name       | Asset file name.                                                                                                                         |
| extension  | Asset file extension.                                                                                                                    |
| imageUrls  | Maps available image widths to respective URLs on CDN. Useful for creating responsive images.                                            |
| categoryId | Category ID the asset belongs to.                                                                                                        |
| size       | Asset file size in bytes.                                                                                                                |
| uploadedAt | Date the asset has been uploaded.                                                                                                        |
| metadata   | Metadata of the asset. This object is format specific, i.e. for images it contains information about picture width and height in pixels. |
| url        | URL to original file on CDN.                                                                                                             |

```
CKBox.mountImageEditor(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    assetId: 'h94eW7EQf4Nt',
    onSave: ({ data }) => {
        console.log('Image has been saved!');
        console.log({ data });
    }
});

```

<a id="ckbox/latest/guides/configuration/localization.html">source file: "ckbox/latest/guides/configuration/localization.html"</a>

## Localization

The default language of the UI is English, but you can choose from over 40 supported languages. If you want to use another language, you have to load its language resources file. Depending on the method of installation, you might want to load language resources using [CDN](#ckbox/latest/guides/configuration/localization.html--cdn), [npm](#ckbox/latest/guides/configuration/localization.html--npm), or [Zip package](#ckbox/latest/guides/configuration/localization.html--zip-package). The language can be then set using the [language](#ckbox/latest/guides/configuration/configuration-options.html--language) configuration option.

In the example below, CKBox is configured to use Spanish.

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    language: 'es'
});

```

<a id="ckbox/latest/guides/configuration/localization.html--including-language-files">

### Including language files

<a id="ckbox/latest/guides/configuration/localization.html--cdn">

#### CDN

If you use CDN, additional language files can be loaded together with CKBox. Use the following URL format to load the language script:  
`https://cdn.ckbox.io/ckbox/2.11.1/translations/[lang-code].js`

```
<script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
<script src="https://cdn.ckbox.io/ckbox/2.11.1/translations/es.js"></script>

```

<a id="ckbox/latest/guides/configuration/localization.html--npm">

#### npm

If you use CKBox as an `npm` dependency, you can `import` the required languages in your application using the following pattern: `import 'ckbox/dist/translations/[lang-code]';`.

```
import * as CKBox from 'ckbox';
import 'ckbox/dist/styles/ckbox.css';
import 'ckbox/dist/translations/es';

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    language: 'es',
});

```

Please note that in this case, it’s still possible to load languages dynamically using the `<script>` tag.

<a id="ckbox/latest/guides/configuration/localization.html--zip-package">

#### Zip package

In the Zip package, language files are located in the `ckbox/translations` folder and can be loaded together with the CKBox script:

```
<script src="ckbox/ckbox.js"></script>
<script src="ckbox/translations/[lang-code].js"></script>

```

<a id="ckbox/latest/guides/configuration/localization.html--list-of-supported-languages">

### List of supported languages

| Language                | Code  |
| ----------------------- | ----- |
| Bengali                 | bn    |
| Bulgarian               | bg    |
| Catalan                 | ca    |
| Chinese (Simplified)    | zh    |
| Chinese (Traditional)   | zh-tw |
| Czech                   | cs    |
| Danish                  | da    |
| Dutch                   | nl    |
| English                 | en    |
| Estonian                | et    |
| Finnish                 | fi    |
| French                  | fr    |
| French (Canada)         | fr-ca |
| German                  | de    |
| Greek                   | el    |
| Hindi                   | hi    |
| Hungarian               | hu    |
| Indonesian              | id    |
| Italian                 | it    |
| Japanese                | ja    |
| Korean                  | ko    |
| Latvian                 | lv    |
| Lithuanian              | lt    |
| Malay                   | ms    |
| Marathi                 | mr    |
| Norwegian               | no    |
| Polish                  | pl    |
| Portuguese (Brazil)     | pt-br |
| Portuguese (Europe)     | pt    |
| Romanian                | ro    |
| Russian                 | ru    |
| Serbian                 | sr    |
| Slovak                  | sk    |
| Spanish (Spain)         | es    |
| Spanish (Latin America) | es-la |
| Spanish (Mexico)        | es-mx |
| Swedish                 | sv    |
| Thai                    | th    |
| Turkish                 | tr    |
| Ukrainian               | uk    |
| Vietnamese              | vi    |

<a id="ckbox/latest/guides/configuration/theming.html">source file: "ckbox/latest/guides/configuration/theming.html"</a>

## Theming

For seamless visual integration of CKBox in your application, you might want to adjust the colors of the UI or create a custom skin.

<a id="ckbox/latest/guides/configuration/theming.html--adjusting-colors">

### Adjusting colors

CKBox exposes several CSS variables that allow controlling the color palette of the whole application. All the colors used in the default skin are derived from the five base colors: `action`, `neutral`, `danger`, `warning`, and `success`. Overriding each of these colors is as simple as setting its HSL values to the appropriate CSS variables.

The most dominant color of the CKBox UI is defined by the `action` color. By adjusting the hue and saturation of this color, you can change the colors of the CKBox palette using just two CSS variables.

<a id="ckbox/latest/guides/configuration/theming.html--list-of-available-color-variables">

#### List of available color variables

You can control the hue and the saturation of each base color using the CSS variables listed in the table below.

| Color   | CSS variables                        | Description                                                            |
| ------- | ------------------------------------ | ---------------------------------------------------------------------- |
| action  | \--ckbox-action-h\--ckbox-action-s   | Base of the most dominant color used for buttons, icons, sliders, etc. |
| neutral | \--ckbox-neutral-h\--ckbox-neutral-s | Color used for neutral backgrounds.                                    |
| success | \--ckbox-success-h\--ckbox-success-s | Color used for success messages.                                       |
| warning | \--ckbox-warning-h\--ckbox-warning-s | Color used for warnings.                                               |
| danger  | \--ckbox-danger-h\--ckbox-danger-s   | Color used for notifications about risky actions and errors.           |

<a id="ckbox/latest/guides/configuration/theming.html--built-in-themes">

### Built-in themes

CKBox comes with an additional built-in `dark` theme. To use it, you have to add the appropriate stylesheet to your webpage. The active theme can be set using the [theme](#ckbox/latest/guides/configuration/configuration-options.html--theme) configuration option.

<a id="ckbox/latest/guides/configuration/theming.html--dark-theme">

#### Dark theme

```
<link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/dark.css">

```

```
CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url',
    theme: 'dark'
});

```

<a id="ckbox/latest/guides/feedback.html">source file: "ckbox/latest/guides/feedback.html"</a>

## Feedback

If you have any kind of suggestions or feedback, or if you need help with integration, please [contact us](https://cksource.com/contact/). We will be really happy to hear from you!

<a id="ckbox/latest/guides/index.html">source file: "ckbox/latest/guides/index.html"</a>

## Getting started with CKBox

Welcome to the setup and configuration section. It includes information about:

* Enabling CKBox on your website.
* Configuring CKBox.
* Integrating CKBox with CKEditor 5.

Use the navigation menu on the left side to browse the documentation.

**See also**

* [CKBox features](#ckbox/latest/features/index.html) – Using and administration of the CKBox file manager on a daily basis
* [Examples](#ckbox/latest/examples/index.html) – Check out various implementations and customizations
* [Support](#ckbox/latest/support/index.html) – Getting help

<a id="ckbox/latest/guides/installation.html">source file: "ckbox/latest/guides/installation.html"</a>

## Installation

CKBox is distributed as an npm package, Zip package, and CDN download. In this guide, you will find the quickest and easiest way to run ready-to-use CKBox application.  
Visit our [GitHub samples repo](https://github.com/ckbox-io/ckbox-examples) to explore more on how to integrate CKBox with your app.

<a id="ckbox/latest/guides/installation.html--cdn">

### CDN

Using a build served from the CDN is the simplest way of embedding CKBox in your application. Additionally, all the scripts served from the CDN are loaded faster, as they are hosted on multiple servers around the globe.

To start using CKBox on your website, embed the following `<script>` tag in the HTML of the page:

```
<script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>

```

Quick example:

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
    </head>
    <body>
        <div id="ckbox"></div>
        <script>
            CKBox.mount(document.getElementById('ckbox'), {
                // You must provide a valid token URL in order to use the application
                // After registering to CKBox, the fastest way to try out CKBox is to use the development token endpoint:
                // https://ckeditor.com/docs/ckbox/2.11.1/guides/configuration/authentication.html#development-token-endpoint
                tokenUrl: 'https://your.token.url'
            });
        </script>
    </body>
</html>

```

<a id="ckbox/latest/guides/installation.html--npm">

### npm

To install CKBox as an NPM dependency, run:

```
npm install ckbox

```

Then you can instantiate CKBox in your code as shown below.

```
import * as CKBox from 'ckbox';
import 'ckbox/dist/styles/ckbox.css';

CKBox.mount(document.querySelector('#ckbox'), {
    tokenUrl: 'https://your.token.url'
});

```

Check out our [code sample](https://github.com/ckbox-io/ckbox-examples/tree/main/esm) on how to use CKBox in your app.

<a id="ckbox/latest/guides/installation.html--zip-package">

### Zip package

[⬇ Download CKBox Zip package (v2.11.1)](https://download.ckbox.io/CKBox/ckbox%5F2.11.1.zip)

Unzip the package to the desired location and attach the `ckbox.js` script on your webpage.

Quick example:

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="ckbox/ckbox.js"></script>
    </head>
    <body>
        <div id="ckbox"></div>
        <script>
            CKBox.mount(document.getElementById('ckbox'), {
                tokenUrl: 'https://your.token.url'
            });
        </script>
    </body>
</html>

```

The Zip package includes a preconfigured `index.html` that will work if you configure the `tokenUrl` option, which has been intentionally left empty.

<a id="ckbox/latest/guides/installation.html--uploader-widget">

### Uploader Widget

The CKBox Uploader Widget is a specialized component designed specifically for file uploads. It provides a streamlined interface focused on uploading files to your CKBox workspace.

<a id="ckbox/latest/guides/installation.html--cdn-installation-for-uploader-widget">

#### CDN Installation for Uploader Widget

To use the uploader widget via CDN, include the same CKBox script and use the `mountUploaderWidget` method:

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
    </head>
    <body>
        <div id="uploader"></div>
        <script>
            CKBox.mountUploaderWidget(document.getElementById('uploader'), {
                tokenUrl: 'https://your.token.url',
                workspaceId: 'your-workspace-id',
                uploadCategoryId: 'your-category-id', // Optional
                uploadFolderId: 'your-folder-id', // Optional
                onUpload: (asset) => {
                    console.log('File uploaded:', asset);
                }
            });
        </script>
    </body>
</html>

```

The uploader widget supports the same authentication methods as the main CKBox widget but focuses specifically on file upload functionality.

<a id="ckbox/latest/guides/installation.html--on-premises">

### On-premises

CKBox can also be installed on-premises. The backend part of the application is installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKBox file manager available in the SaaS version.

Please refer to the [CKBox On-premises Documentation](#cs/latest/onpremises/ckbox-onpremises/overview.html) to read about the system requirements, configuration and supported data storages.

<a id="ckbox/latest/guides/integrations/frameworks/angular-integration.html">source file: "ckbox/latest/guides/integrations/frameworks/angular-integration.html"</a>

## Angular

If you would like to use CKBox in an Angular application, start by installing the `ckbox` package as described int [this guide](#ckbox/latest/guides/installation.html--npm). Then, within Angular component, access the reference to a `<div />` element and use it to instantiate CKBox in the `ngAfterViewInit` lifecycle method.

Shown below is the content of an example Angular component file:

```
import { AfterViewInit, Component, ElementRef, ViewChild } from "@angular/core";
import * as CKBox from "ckbox";

@Component({
    selector: "ckbox-sample",
    templateUrl: "./ckbox-sample.component.html",
    styleUrls: ["./ckbox-sample.component.css"],
})
export class CKBoxSampleComponent implements AfterViewInit {
    @ViewChild("ckbox") ckboxRoot?: ElementRef;

    ngAfterViewInit(): void {
        CKBox.mount(this.ckboxRoot?.nativeElement, {
            tokenUrl: "https://your.token.url",
        });
    }
}

```

Place the following snippet inside the component’s template file:

```
<div #ckbox></div>

```

Finally, add styling to the root `styles.css` file:

```
@import "../node_modules/ckbox/dist/styles/ckbox.css";

```

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html">source file: "ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html"</a>

## ASP.NET Core

This guide describes the integration with an ASP.NET Core application. If you prefer to jump straight to the code, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-aspdotnet-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--prerequisites">

### Prerequisites

Before we start, please make sure that you have `.NET SDK 7.0` installed in your system. If the `dotnet` tool is not available from the command line, please visit the [.NET SDK download page](https://www.microsoft.com/net/core) first.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--creating-the-application">

### Creating the application

As a base in our example, we will create a new project directory and an empty ASP.NET project using the following command:

```
dotnet new web --name AspdotnetCkbox

```

After the project is created, you can start the development server:

```
cd AspdotnetCkbox
dotnet run

```

The application will be available under a port listed in the console, for example, <http://localhost:5063>. The port can also be adjusted in the `Properties/launchSettings.json` file.

```
{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:52536",
      "sslPort": 44341
    }
  },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5063",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7029;http://localhost:5063",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

```

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--creating-the-token-endpoint">

### Creating the Token endpoint

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. For information on how to create access credentials, please refer to the [Creating access credentials](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) section in the [Authentication](#ckbox/latest/guides/configuration/authentication.html) guide.

Now that we have the required access credentials, namely: the environment ID and the access key, let’s create the token endpoint.

First, let’s install the [System.IdentityModel.Tokens.Jwt](https://www.nuget.org/packages/System.IdentityModel.Tokens.Jwt/) package for creating JWT tokens.

```
dotnet add package System.IdentityModel.Tokens.Jwt

```

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--complete-endpoint-code">

#### Complete endpoint code

```
// Program.cs
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/token", () =>
{

    var environmentId = builder.Configuration.GetValue<string>("CKBoxEnvironmentId");
    var accessKey = builder.Configuration.GetValue<string>("CKBoxAccessKey");
    var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(accessKey));

    var signingCredentials = new SigningCredentials(securityKey, "HS256");
    var header = new JwtHeader(signingCredentials);

    var dateTimeOffset = new DateTimeOffset(DateTime.UtcNow);

    var payload = new JwtPayload
    {
        { "aud", environmentId },
        { "iat", dateTimeOffset.ToUnixTimeSeconds() },
        { "sub", "user-123" },
        { "user", new Dictionary<string, string> {
            { "email", "joe.doe@example.com" },
            { "name", "Joe Doe" }
        } },
        { "auth", new Dictionary<string, object> {
            { "ckbox", new Dictionary<string, string> {
                { "role", "admin" }
            } }
        } }
    };

    var securityToken = new JwtSecurityToken(header, payload);
    var handler = new JwtSecurityTokenHandler();

    return handler.WriteToken(securityToken);
});

app.Run();

```

As you can see on the code listing above, the access credentials required to sign JWT tokens are obtained from the Configuration object. Thanks to this you can conveniently add them to the `appsettings.json` file:

```
{
  "CKBoxAccessKey": "REPLACE-WITH-ACCESS-KEY",
  "CKBoxEnvironmentId": "REPLACE-WITH-ENVIRONMENT-ID",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

```

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--adding-ckbox-script-to-the-page">

### Adding CKBox script to the page

CKBox can be embedded in the application in [multiple ways](#ckbox/latest/guides/installation.html). For simplicity, in our example, we will use the CKBox script served from the CDN.

Examples in this guide will cover three popular scenarios of using CKBox:

* CKBox integrated with CKEditor 5.
* CKBox used as a file picker in dialog mode.
* CKBox used as a full-page application.

First, let’s add Razor templating support to our application.

```
// Program.cs
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();

app.MapGet("/token", () =>
{

    var environmentId = builder.Configuration.GetValue<string>("CKBoxEnvironmentId");
    var accessKey = builder.Configuration.GetValue<string>("CKBoxAccessKey");
    var securityKey = new SymmetricSecurityKey(Encoding.ASCII.GetBytes(accessKey));

    var signingCredentials = new SigningCredentials(securityKey, "HS256");
    var header = new JwtHeader(signingCredentials);

    var dateTimeOffset = new DateTimeOffset(DateTime.UtcNow);

    var payload = new JwtPayload
    {
        { "aud", environmentId },
        { "iat", dateTimeOffset.ToUnixTimeSeconds() },
        { "sub", "user-123" },
        { "user", new Dictionary<string, string> {
            { "email", "joe.doe@example.com" },
            { "name", "Joe Doe" }
        } },
        { "auth", new Dictionary<string, object> {
            { "ckbox", new Dictionary<string, string> {
                { "role", "admin" }
            } }
        } }
    };

    var securityToken = new JwtSecurityToken(header, payload);
    var handler = new JwtSecurityTokenHandler();

    return handler.WriteToken(securityToken);
});

app.MapRazorPages();
app.Run();

```

To avoid code repetition, let’s prepare a base layout that includes the CKBox script, which we will reuse in all three examples:

`Pages/Shared/_Layout.cshtml`

```
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8"/>
    <title>CKBox example</title>
    <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
    @await RenderSectionAsync("Head", required: false)
</head>
<body>

@RenderBody()

</body>
</html>

```

Now, let’s add pages for the three examples.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--ckbox-with-ckeditor-5">

#### CKBox with CKEditor 5

In this example, we will use the quickest and easiest way to run CKEditor 5 – served from the CDN. For more advanced integration scenarios, please refer to the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/installation/index.html).

Let’s create the child view that extends the layout we have created in the previous step:

`Pages/index.cshtml`

```
@page

@{
    Layout = "Shared/_Layout";
    var tokenUrl = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}/token";
}

@section Head {
    <script type="importmap">
        {
            "imports": {
                "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
                "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"
            }
        }
    </script>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
}
<div>
    <textarea id="editor">@Html.Raw("Hello world")</textarea>

    <script type="module">
        import {
            ClassicEditor,
            CKBox,
            Essentials,
            Bold,
            Italic,
            Font,
            Paragraph
        } from 'ckeditor5';

        ClassicEditor
            .create( document.querySelector( '#editor' ), {
                plugins: [ CKBox, Essentials, Bold, Italic, Font, Paragraph ],
                ckbox: {
                    tokenUrl: 'https://your.token.url',
                    theme: 'lark'
                },
                toolbar: [
                    'ckbox', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                    'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                ],
            } )
            .catch( error => {
                console.error( error );
            } );
    </script>
</div>

```

The above example includes a [predefined CKEditor 5 build](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/predefined-builds.html) from the CDN, which includes the required [CKBox plugin](#ckeditor5/latest/features/file-management/ckbox.html--installation). Then, CKEditor 5 is configured to use CKBox by setting the required parameters of the `ckbox` attribute. Please note that in the `ckbox.tokenUrl` configuration option we pass the URL of the token endpoint created in one of the previous steps, which will be used to obtain JWT tokens used to authenticate users in CKBox.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--ckbox-as-file-picker">

#### CKBox as file picker

One of the common scenarios is to use CKBox as a file picker, where the user can choose one of the files stored in the file manager. After choosing the file, we want to obtain information about the chosen files, especially their URLs. This can be achieved using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback passed as the CKBox’s configuration option:

`Pages/filePicker.cshtml`

```
@page

@{
    Layout = "Shared/_Layout";
    var tokenUrl = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}/token";
}

<div>
    <input type="text" id="file-url"></input><button id="choose">Choose file</button>
        <div id="ckbox"></div>
        <script>
            document.getElementById('choose').addEventListener('click', function () {
                CKBox.mount(document.querySelector('#ckbox'), {
                    tokenUrl: '@tokenUrl',
                    dialog: true,
                    assets: {
                        // Callback executed after choosing assets
                        onChoose: (assets) => {
                            document.getElementById('file-url').value = assets[0].data.url;
                            assets.forEach((asset) => {
                                console.log(asset.data.url);
                            })
                        }
                    }
                });
            });
        </script>
</div>

```

The example will be available under <http://localhost:5063/filePicker>.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--ckbox-in-full-page-mode">

#### CKBox in full-page mode

To start CKBox in full-page mode, you can attach it to the `document.body` and adjust the required CSS styles:

`Pages/fullPage.cshtml`

```
@page

@{
    Layout = "Shared/_Layout";
    var tokenUrl = $"{HttpContext.Request.Scheme}://{HttpContext.Request.Host}/token";
}

@section Head {
    <style>
            html, body {
                margin: 0;
                padding: 0;
                height: 100vh;
            }
    </style>
}

<div>
    <script>
        CKBox.mount(document.body, {
            tokenUrl: '@tokenUrl',
        });
    </script>
</div>

```

The example will be available under <http://localhost:5063/fullPage>.

<a id="ckbox/latest/guides/integrations/frameworks/aspdotnetcore.html--complete-code">

### Complete code

On GitHub, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-aspdotnet-example) described in this guide.

<a id="ckbox/latest/guides/integrations/frameworks/express.html">source file: "ckbox/latest/guides/integrations/frameworks/express.html"</a>

## Express

This guide describes the integration of CKBox in an Express application. If you prefer to jump straight to the code, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-express-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/express.html--prerequisites">

### Prerequisites

Before we start, please ensure that you have a recent LTS version of Node.js installed in your system. If the tool is not available from the command line, please follow the [Node.js](https://nodejs.org/en) download instructions first.

<a id="ckbox/latest/guides/integrations/frameworks/express.html--creating-the-application">

### Creating the application

As a base in our example, we will use a project created with [Express project generator](https://expressjs.com/en/starter/generator.html). To start, let’s create a directory for the app, enter it, and use the following command:

```
npx express-generator --view=ejs --git

```

After the project is created, update the list of dependencies and install packages:

```
npx ncu -u && npm install

```

Finally, we can remove `routes/users.js` and `public/stylesheets/style.css` files from the template since we won’t be using them.

<a id="ckbox/latest/guides/integrations/frameworks/express.html--environment-variables">

### Environment variables

The app we are building relies on a few variables that would be better kept secret. Therefore, before jumping onto the next steps, let’s create a `.env` file in the project’s root. Over the course of this guide, we will be adding our envrionment variables there.

Let’s install the `dotenv` package that will help us use the `.env` file in the project:

```
npm add dotenv

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--authentication">

### Authentication

In a typical scenario access to CKBox will be restricted to [authenticated](#ckbox/latest/guides/configuration/authentication.html) users only. Therefore, we will introduce a simple authentication mechanism with the help of [Passport](https://www.passportjs.org/) to our app. Let’s start by installing the required dependencies. For simplicity, we are omitting CSRF protection measures in the app. Please note this example uses a simplified approach that should not necessarily be used in your production application.

```
npm add passport passport-local express-session connect-ensure-login

```

Then, let’s create a `routes/auth.js` router that will take care of user authentication. We will be using 3 test users and each one of them will be assigned a different CKBox role: `user`, `admin`, or `superadmin`. Passport’s method `passport.serializeUser` will make sure that the user’s info, including their role in CKBox, will be made available for other route handlers.

Below you can find the complete code for handlers within the authentication router.

```
// routes/auth.js

const express = require("express");
const passport = require("passport");
const LocalStrategy = require("passport-local");

const dbUsers = [
    {
        id: "1",
        role: "user",
        email: "user@acme.com",
        password: "testpwd123",
        name: "John",
    },
    {
        id: "2",
        role: "admin",
        email: "admin@acme.com",
        password: "testpwd123",
        name: "Joe",
    },
    {
        id: "3",
        role: "superadmin",
        email: "superadmin@acme.com",
        password: "testpwd123",
        name: "Alice",
    },
];

passport.use(
    new LocalStrategy({ usernameField: "email" }, function (email, password, done) {
        const dbUser = dbUsers.find(function (dbUser) {
            return dbUser.email === email && dbUser.password === password;
        });

        if (!dbUser) {
            return done(null, false);
        }

        return done(null, dbUser);
    })
);

passport.serializeUser(function (user, cb) {
    process.nextTick(function () {
        cb(null, { id: user.id, name: user.name, role: user.role });
    });
});

passport.deserializeUser(function (user, cb) {
    process.nextTick(function () {
        return cb(null, user);
    });
});

const router = express.Router();

router.get("/login", function (req, res, next) {
    res.render("login");
});

router.post(
    "/login/password",
    passport.authenticate("local", {
        successReturnToOrRedirect: "/",
        failureRedirect: "/login",
        failureMessage: true,
    })
);

router.post("/logout", function (req, res, next) {
    req.logout(function (err) {
        if (err) {
            return next(err);
        }

        res.redirect("/");
    });
});

module.exports = router;

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--token-url">

### Token URL

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the [Customer Portal](https://portal.ckeditor.com). For information on how to create access credentials, please refer to the [Creating access credentials](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) article in the [Authentication guide](#ckbox/latest/guides/configuration/authentication.html).

Now that we have the required access credentials, namely: the environment ID and the access key, let’s create the token endpoint. As a base, we will use the code of the [generic token endpoint in Node.js](#cs/latest/examples/token-endpoints/nodejs.html).

First, let’s install the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) library for creating JWT tokens:

```
npm add jsonwebtoken

```

Let’s wrap the logic of the Node.js token endpoint with the Express route handler and generate a token with the [payload required by CKBox](#ckbox/latest/guides/configuration/authentication.html--token-payload). Please note that access to this endpoint is limited to authenticated users only.

Let’s create an Express router that will handle all requests related to CKBox. We will rely on the `req.user` object set by Passport for authenticated users.

```
// routes/ckbox.js

const express = require("express");
const jwt = require("jsonwebtoken");

const CKBOX_ENVIRONMENT_ID = process.env.CKBOX_ENVIRONMENT_ID;
const CKBOX_ACCESS_KEY = process.env.CKBOX_ACCESS_KEY;

const router = express.Router();

router.get("/api/ckbox", function (req, res, next) {
    const user = req.user;

    if (user && user.role) {
        const payload = {
            aud: CKBOX_ENVIRONMENT_ID,
            sub: user.id,
            auth: {
                ckbox: {
                    role: user.role,
                },
            },
        };

        const result = jwt.sign(payload, CKBOX_ACCESS_KEY, {
            algorithm: "HS256",
            expiresIn: "1h",
        });

        res.send(result);
    } else {
        next({ message: "Unauthenticated user", status: 401 });
    }
});

module.exports = router;

```

As you can see on the code listing above, the access credentials required to sign JWT tokens are obtained from the environment variables. Thanks to this, you can conveniently add them to the `.env` file:

```
# .env
CKBOX_ENVIRONMENT_ID=REPLACE-WITH-ENVIRONMENT-ID
CKBOX_ACCESS_KEY=REPLACE-WITH-ACCESS-KEY

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--views">

### Views

Now, let’s build a couple of views. We will be using Tailwind CSS to bring an appealing look to our example app. For simplicity, we will be using the Play CDN to use Tailwind right in the browser without any build steps. Please note that [this approach](https://tailwindcss.com/docs/installation/play-cdn) is not the best choice for production.

<a id="ckbox/latest/guides/integrations/frameworks/express.html--login-view">

#### Login view

Let’s start by creating a simple login view under `views/login.ejs`. Users will be providing their email addresses and passwords, and we will be using `/login/password` handler created before to authenticate them.

```
<!-- views/login.ejs -->

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://cdn.tailwindcss.com"></script>
        <title>Login</title>
    </head>
    <body>
        <section class="flex justify-center items-center h-screen">
            <form
                action="/login/password"
                method="post"
                class="bg-blue-500 text-center w-1/2 xl:w-1/3 px-3 py-4 rounded flex flex-col gap-2"
            >
                <section class="flex flex-col gap-1">
                    <label for="email" class="text-left text-white">Email</label>
                    <input
                        id="email"
                        name="email"
                        type="text"
                        required
                        autofocus
                        class="block w-full mx-auto text-sm py-2 px-3 rounded"
                    />
                </section>
                <section class="flex flex-col gap-1">
                    <label for="password" class="text-left text-white">Password</label>
                    <input
                        id="current-password"
                        name="password"
                        type="password"
                        required
                        class="block w-full mx-auto text-sm py-2 px-3 rounded my-3"
                    />
                </section>
                <button
                    type="submit"
                    class="bg-blue text-white font-bold py-2 px-4 rounded border block mx-auto w-full"
                >
                    Login
                </button>
            </form>
        </section>
    </body>
</html>

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--ckbox-with-ckeditor">

#### CKBox with CKEditor

In the `views/ckeditor.ejs` view, we will be using the quickest and easiest way to run CKEditor 5 – served from the CDN. For more advanced integration scenarios, please refer to the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/installation/index.html).

```
<!-- views/ckeditor.ejs -->

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://cdn.tailwindcss.com"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/classic/ckeditor.js"></script>
        <link
            rel="stylesheet"
            href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/lark.css"
        />
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <title>CKEditor</title>
        <style>
            .ck-editor__editable_inline {
                min-height: 400px;
            }
        </style>
    </head>
    <body>
        <div class="mx-auto h-screen flex flex-col">
            <%- include('nav'); %>
            <div class="px-8 flex-1 bg-accents-0">
                <main class="w-full max-w-4xl mx-auto py-16 h-full flex flex-col">
                    <section class="flex flex-col gap-6">
                        <h2 class="text-4xl font-semibold tracking-tight">CKEditor</h2>
                    </section>
                    <hr class="border-t border-accents-2 my-6" />
                    <section class="flex flex-col gap-3 h-4/5">
                        In this example CKBox is integrated with CKEditor. With CKBox plugin,
                        CKEditor will upload files directly to your CKBox environment. Use icon in
                        the top-left corner of the editor to open CKBox as a file picker.
                        <div id="editor"></div>
                    </section>
                </main>
            </div>
        </div>

        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
                    "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"
                }
            }
        </script>

        <script type="module">
            import {
                ClassicEditor,
                CKBox,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } from 'ckeditor5';

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    plugins: [ CKBox, Essentials, Bold, Italic, Font, Paragraph ],
                    ckbox: {
                        tokenUrl: "<%= tokenUrl %>",
                        theme: 'lark'
                    },
                    toolbar: [
                        'ckbox', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

As you can notice, the view relies on the `nav.ejs` partial, a reusable navigation bar that will be located in most views in our app. Therefore, let’s add the `views/nav.ejs` file.

```
<!-- views/nav.ejs -->

<nav
    class="border-b border-gray-200 py-5 relative z-20 bg-background shadow-[0_0_15px_0_rgb(0,0,0,0.1)]"
>
    <div class="flex items-center lg:px-6 px-8 mx-auto max-w-7xl">
        <div class="flex-1 hidden md:flex">
            <a href="/" class="text-blue-600 hover:text-blue-800 visited:text-purple-600">Home</a>
        </div>
        <div class="flex-1 justify-end flex items-center md:flex gap-3 h-8">
            <% if (name) { %>
            <span>Welcome, <%= name %>!</span>
            <form action="/logout" method="post">
                <button
                    type="submit"
                    class="text-white bg-blue-600 hover:bg-blue-700 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-4 py-1.5"
                >
                    Sign out
                </button>
            </form>
            <% } else { %>
            <a
                href="/login"
                class="text-white bg-blue-600 hover:bg-blue-700 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-4 py-1.5"
                >Sign in</a
            >
            <% } %>
            <a
                href="https://github.com/ckbox-io/ckbox-express-example"
                target="_blank"
                rel="noreferrer"
                class="text-blue-600 hover:text-blue-800 visited:text-purple-600"
            >
                GitHub
            </a>
        </div>
    </div>
</nav>

```

Then, let’s declare a route for this view in the `routes/ckbox.js` file.

```
// routes/ckbox.js

// ...

const ensureLoggedIn = require("connect-ensure-login").ensureLoggedIn;
const PUBLIC_URL = process.env.PUBLIC_URL;

router.get("/ckeditor", ensureLoggedIn(), function (req, res) {
    res.render("ckeditor", {
        name: req.user.name,
        tokenUrl: `${PUBLIC_URL}/api/ckbox`,
    });
});

// ...

```

Finally, let’s take the opportunity to add the `PUBLIC_URL=http://localhost:3000` entry to the `.env` file.

<a id="ckbox/latest/guides/integrations/frameworks/express.html--ckbox-as-file-picker">

#### CKBox as file picker

One of the common scenarios is to use CKBox as a file picker, where the user can choose one of the files stored in the file manager. After choosing the file, we want to obtain information about the chosen files, especially their URLs. This can be achieved using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback passed as the CKBox’s configuration option.

Below is the code snippet for the `views/file-picker.ejs` view.

```
<!-- views/file-picker.ejs -->

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://cdn.tailwindcss.com"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <title>File picker</title>
    </head>
    <body>
        <div class="mx-auto h-screen flex flex-col">
            <%- include('nav'); %>
            <div class="px-8 flex-1 bg-accents-0">
                <main class="w-full max-w-4xl mx-auto py-16 h-full flex flex-col">
                    <section class="flex flex-col gap-6">
                        <h2 class="text-4xl font-semibold tracking-tight">File Picker</h2>
                    </section>
                    <hr class="border-t border-accents-2 my-6" />
                    <section class="flex flex-col gap-3">
                        One of the common scenarios is to use CKBox as a file picker, where the user
                        can choose one of the files stored in the file manager. After choosing the
                        file, we want to obtain information about the chosen files, especially their
                        URLs.
                        <div>
                            <button
                                id="choose-assets"
                                class="text-white bg-blue-600 hover:bg-blue-700 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-4 py-1.5"
                            >
                                Choose assets
                            </button>
                        </div>
                        <div id="ckbox"></div>
                    </section>
                    <section class="flex flex-col gap-3">
                        <ul id="assets-list"></ul>
                    </section>
                </main>
            </div>
        </div>
        <script>
            const chooseBtn = document.getElementById("choose-assets");
            const assetsList = document.getElementById("assets-list");

            const handleChoose = (assets) => {
                assetsList.innerHTML = "";

                const name = assets.forEach(({ data }) => {
                    const item = document.createElement("li");
                    const name = document.createElement("span");

                    name.textContent = `${data.name}.${data.extension}`;

                    if (data.url) {
                        const link = document.createElement("a");
                        const linkClasses = [
                            "text-blue-600",
                            "hover:text-blue-800",
                            "visited:text-purple-600",
                        ];

                        link.classList.add(...linkClasses);
                        link.setAttribute("href", data.url);
                        link.setAttribute("target", "_blank");
                        link.setAttribute("rel", "noreferrer");

                        link.appendChild(name);
                        item.appendChild(link);
                    } else {
                        item.appendChild(name);
                    }

                    assetsList.appendChild(item);
                });
            };

            chooseBtn.addEventListener("click", () => {
                CKBox.mount(document.getElementById("ckbox"), {
                    tokenUrl: "<%= tokenUrl %>",
                    dialog: true,
                    assets: { onChoose: handleChoose },
                });
            });
        </script>
    </body>
</html>

```

Then, let’s declare a route for this view in the `routes/ckbox.js` file.

```
// routes/ckbox.js

// ...

router.get("/file-picker", ensureLoggedIn(), function (req, res) {
    res.render("file-picker", {
        name: req.user.name,
        tokenUrl: `${PUBLIC_URL}/api/ckbox`,
    });
});

// ...

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--ckbox-in-inline-mode">

#### CKBox in inline mode

To initialize CKBox in inline mode, you can simply mount it in the desired place of your app. This is the default embedding mode for CKBox, so no additional configuration props besides `tokenUrl` are required. CKBox will occupy as much space as allowed by its parent element.

Below is the code snippet for the `views/inline.ejs` view.

```
<!-- views/inline.ejs -->

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://cdn.tailwindcss.com"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <title>Inline</title>
    </head>
    <body>
        <div class="mx-auto h-screen flex flex-col">
            <%- include('nav'); %>
            <div class="px-8 flex-1 bg-accents-0">
                <main class="w-full max-w-4xl mx-auto py-16 h-full flex flex-col">
                    <section class="flex flex-col gap-6">
                        <h2 class="text-4xl font-semibold tracking-tight">Inline</h2>
                    </section>
                    <hr class="border-t border-accents-2 my-6" />
                    <section class="flex flex-col gap-3 flex-1">
                        <p>
                            To start CKBox in inline mode, you can instantiate it in an arbitrary
                            container. CKBox will respect height and width of the container.
                        </p>
                        <div id="ckbox" class="h-full"></div>
                    </section>
                </main>
            </div>
        </div>
        <script>
            CKBox.mount(document.getElementById("ckbox"), {
                tokenUrl: "<%= tokenUrl %>",
            });
        </script>
    </body>
</html>

```

Then, let’s declare a route for this view in the `routes/ckbox.js` file.

```
// routes/ckbox.js

// ...

router.get("/inline", ensureLoggedIn(), function (req, res) {
    res.render("inline", {
        name: req.user.name,
        tokenUrl: `${PUBLIC_URL}/api/ckbox`,
    });
});

// ...

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--home-page">

### Home page

Finally, let’s tweak the home page so that it displays links to all views created above. Therefore, let’s replace the contents of the initial `views/index.ejs` file with the snippet outlined below.

```
<!-- views/index.ejs -->

<!doctype html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <script src="https://cdn.tailwindcss.com"></script>
        <title>Express</title>
    </head>
    <body>
        <div class="mx-auto h-screen flex flex-col">
            <%- include('nav'); %>
            <div class="px-8 flex-1 bg-accents-0">
                <main class="w-full max-w-4xl mx-auto py-16 h-full flex flex-col">
                    <section class="flex flex-col gap-6">
                        <h2 class="text-3xl font-semibold tracking-tight">
                            CKBox integration with Express
                        </h2>
                    </section>
                    <hr class="border-t border-accents-2 my-6" />
                    <section class="flex flex-col gap-3">
                        <p>Below you can find example integrations of CKBox.</p>
                        <p>
                            In a typical scenario access to CKBox will be restricted to
                            authenticated users only. Therefore, each sample is restricted to signed
                            in users only. Use different credentials to unlock various CKBox roles.
                            See available users
                            <a
                                href="https://github.com/ckbox-io/ckbox-express-example/blob/main/routes/auth.js"
                                target="_blank"
                                rel="noreferrer"
                                class="text-blue-600 hover:text-blue-800"
                                >here</a
                            >.
                        </p>
                        <div class="flex-1 hidden md:flex gap-2">
                            <ol>
                                <li>
                                    <a class="text-blue-600 hover:text-blue-800" href="/inline"
                                        >Inline mode</a
                                    >
                                </li>
                                <li>
                                    <a class="text-blue-600 hover:text-blue-800" href="/file-picker"
                                        >File picker</a
                                    >
                                </li>
                                <li>
                                    <a class="text-blue-600 hover:text-blue-800" href="/ckeditor"
                                        >CKEditor</a
                                    >
                                </li>
                            </ol>
                        </div>
                    </section>
                </main>
            </div>
        </div>
    </body>
</html>

```

Also, let’s adjust the index router by replacing the contents of the `routes/index.js` file with the following snippet:

```
const express = require("express");
const router = express.Router();

router.get("/", function (req, res) {
    res.render("index", { name: req.user?.name });
});

module.exports = router;

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--app">

### App

Finally, let’s combine all routes with the main `app.js` file. Replace the file’s contents with the snippet below.

```
const createError = require("http-errors");
const express = require("express");
const path = require("path");
const session = require("express-session");
const cookieParser = require("cookie-parser");
const logger = require("morgan");
const passport = require("passport");

require("dotenv").config();

const indexRouter = require("./routes/index");
const ckboxRouter = require("./routes/ckbox");
const authRouter = require("./routes/auth");

const app = express();

app.set("views", path.join(__dirname, "views"));
app.set("view engine", "ejs");

app.use(logger("dev"));
app.use(express.json());
app.use(express.urlencoded({ extended: false }));
app.use(cookieParser());
app.use(express.static(path.join(__dirname, "public")));

app.use(
    session({
        secret: process.env.SESSION_SECRET,
        resave: false,
        saveUninitialized: true,
    })
);
app.use(passport.authenticate("session"));

app.use("/", indexRouter);
app.use("/", authRouter);
app.use("/", ckboxRouter);

app.use(function (req, res, next) {
    next(createError(404));
});

app.use(function (err, req, res, next) {
    res.locals.message = err.message;
    res.locals.error = req.app.get("env") === "development" ? err : {};
    res.status(err.status || 500);
    res.render("error");
});

module.exports = app;

```

User sessions established with the help of the `express-session` package are kept in memory. Therefore, you must sign in again anytime the Express app is started.

As you can see, we’ve used one more environment variable: `SESSION_SECRET`. Its value is used by the [express-session](https://www.npmjs.com/package/express-session) package to sign the session ID cookie and would best be a random set of characters. Below is the complete content of the `.env` file.

```
# .env
CKBOX_ENVIRONMENT_ID=REPLACE-WITH-ENVIRONMENT-ID
CKBOX_ACCESS_KEY=REPLACE-WITH-ACCESS-KEY
PUBLIC_URL=http://localhost:3000
SESSION_SECRET=KdTwwFg0zOd3Bp4INE2UmnEogLJK5uma1wdYABaaODs=

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--congratulations">

### Congratulations

Congratulations on completing the guide! You can now access the app by running the following command:

```
npm start

```

<a id="ckbox/latest/guides/integrations/frameworks/express.html--complete-code">

### Complete code

On GitHub, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-express-example) described in this guide.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html">source file: "ckbox/latest/guides/integrations/frameworks/laravel.html"</a>

## Laravel

This guide describes the integration of CKBox in a Laravel application. If you prefer to jump straight to the code, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-laravel-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--prerequisites">

### Prerequisites

Before we start, please ensure that you have `composer` installed in your system. If the tool is not available from the command line, please follow [Composer’s installation instructions](https://getcomposer.org/download/) first.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--creating-the-application">

### Creating the application

As a base in our example, we will create a new Laravel project using the Composer `create-project` command:

```
composer create-project laravel/laravel ckbox-laravel-example

```

After the project is created, you can enter the directory and start the development server:

```
cd ckbox-laravel-example
php artisan serve

```

The application will be available under <http://127.0.0.1:8000>.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--creating-the-controller">

### Creating the controller

First, let’s create a controller. The controller will contain two actions: one for displaying the HTML content of the example and the second one for serving the token URL, used to authenticate users in CKBox.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--token-url">

#### Token URL

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the [Customer Portal](https://portal.ckeditor.com). For information on how to create access credentials, please refer to the [Creating access credentials](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) article in the [Authentication guide](#ckbox/latest/guides/configuration/authentication.html)

Now that we have the required access credentials, namely: the environment ID and the access key, let’s create the token endpoint. As a base, we will use the code of the [generic token endpoint in PHP](#cs/latest/examples/token-endpoints/php.html).

First, let’s install the [firebase/php-jwt](https://github.com/firebase/php-jwt) library for creating JWT tokens:

```
composer require firebase/php-jwt

```

As a base, we will use the code of the [generic token endpoint in PHP](#cs/latest/examples/token-endpoints/php.html). Let’s wrap the logic of the PHP token endpoint in Laravel action and generate a token with the [payload required by CKBox](#ckbox/latest/guides/configuration/authentication.html--token-payload).

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--complete-controller-code">

#### Complete controller code

```
// app/Http/Controllers/CKBoxExampleController.php

namespace App\Http\Controllers;

use \Firebase\JWT\JWT;
use Illuminate\Http\Response;
use Illuminate\View\View;

class CKBoxExampleController extends Controller
{
    /**
     * Show the CKBox example.
     */
    public function show(string $example = null): View
    {
        if (in_array($example, ['ckeditor', 'modal', 'full-page'])) {
            return view('ckbox-example-' . $example);
        }

        return view('ckbox-example-list');
    }

    /**
     * Create CKBox JWT token.
     */
    public function token(): Response
    {
        $environmentId = env('CKBOX_ENVIRONMENT_ID');
        $accessKey = env('CKBOX_ACCESS_KEY');

        $payload = [
            'aud' => $environmentId,
            'iat' => time(),
            'sub' => 'unique-user-id', // Unique user ID in your application
            'auth' => [
                'ckbox' => [
                    'role' => 'superadmin',
                ]
            ]
        ];

        $jwtToken = JWT::encode($payload, $accessKey, 'HS256');

        return new Response($jwtToken);
    }
}

```

As you can see on the code listing above, the access credentials required to sign JWT tokens are obtained from the environment variables. Thanks to this, you can conveniently add them to the `.env` file:

```
# .env
CKBOX_ENVIRONMENT_ID=REPLACE-WITH-ENVIRONMENT-ID
CKBOX_ACCESS_KEY=REPLACE-WITH-ACCESS-KEY

```

Now, let’s register the required routes:

```
// routes/web.php

use App\Http\Controllers\CKBoxExampleController;
use Illuminate\Support\Facades\Route;

Route::get('/ckbox/token', [CKBoxExampleController::class, 'token'])->name('ckbox_token');
Route::get('/{example?}', [CKBoxExampleController::class, 'show'])->name('ckbox_example');

```

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--adding-ckbox-script-to-the-page">

### Adding CKBox script to the page

CKBox can be embedded in the application in [multiple ways](#ckbox/latest/guides/installation.html). For simplicity, in our example, we will use the CKBox script served from the CDN.

Examples in this guide will cover three popular scenarios of using CKBox:

* CKBox integrated with CKEditor
* CKBox used as a file picker in dialog mode
* CKBox used as a full-page application

To avoid code repetition, let’s prepare a base Blade template that includes CKBox script, which we will reuse in all three examples:

```
<!-- resources/views/ckbox-example-layout.blade.php -->
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8"/>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        @stack('head')
        <title>CKBox example</title>
    </head>
    <body>
    @yield('content')
    </body>
</html>

```

Now, let’s add views for the three examples.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--ckbox-with-ckeditor-5">

#### CKBox with CKEditor 5

In this example, we will use the quickest and easiest way to run CKEditor 5 – served from the CDN. For more advanced integration scenarios, please refer to the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/installation/index.html).

Let’s create the child view that extends the layout we have created in the previous step:

```
<!-- resources/views/ckbox-example-ckeditor.blade.php -->
@extends('ckbox-example-layout')

@push('head')
    <script type="importmap">
        {
            "imports": {
                "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
                "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"
            }
        }
    </script>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
@endpush

@section('content')
    <textarea id="editor"><?php echo htmlspecialchars('<h1>Example</h1><p>Hello world</p>'); ?></textarea>

    <script type="module">
        import {
            ClassicEditor,
            CKBox,
            Essentials,
            Bold,
            Italic,
            Font,
            Paragraph
        } from 'ckeditor5';

        ClassicEditor
            .create( document.querySelector( '#editor' ), {
                plugins: [ CKBox, Essentials, Bold, Italic, Font, Paragraph ],
                ckbox: {
                    tokenUrl: 'https://your.token.url',
                    theme: 'lark'
                },
                toolbar: [
                    'ckbox', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                    'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                ],
            } )
            .catch( error => {
                console.error( error );
            } );
    </script>
@endsection

```

The above example includes a [predefined CKEditor build](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/predefined-builds.html) from the CDN, which includes the required [CKBox plugin](#ckeditor5/latest/features/file-management/ckbox.html--installation). Then, CKEditor is configured to use CKBox by setting the required parameters of the `ckbox` attribute. Please note that in the `ckbox.tokenUrl` configuration option we pass the URL of the token endpoint created in one of the previous steps, which will be used to obtain JWT tokens used to authenticate users in CKBox.

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--ckbox-as-file-picker">

#### CKBox as file picker

One of the common scenarios is to use CKBox as a file picker, where the user can choose one of the files stored in the file manager. After choosing the file, we want to obtain information about the chosen files, especially their URLs. This can be achieved using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback passed as the CKBox’s configuration option:

```
<!-- resources/views/ckbox-example-modal.blade.php -->
@extends('ckbox-example-layout')

@section('content')
    <input type="text" id="file-url"></input><button id="choose">Choose file</button>
    <div id="ckbox"></div>
    <script>
        document.getElementById('choose').addEventListener('click', function () {
            CKBox.mount(document.querySelector('#ckbox'), {
                tokenUrl: '{{ route('ckbox_token') }}',
                dialog: true,
                assets: {
                    // Callback executed after choosing assets
                    onChoose: (assets) => {
                        document.getElementById('file-url').value = assets[0].data.url;

                        assets.forEach((asset) => {
                            console.log(asset.data.url);
                        })
                    }
                }
            });
        });
    </script>
@endsection

```

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--ckbox-in-full-page-mode">

#### CKBox in full-page mode

To start CKBox in full-page mode, you can attach it to the `document.body` and adjust the required CSS styles:

```
@extends('ckbox-example-layout')

@push('head')
    <style>
        html, body {
            margin: 0;
            padding: 0;
            height: 100vh;
        }
    </style>
@endpush

@section('content')
    <script>
        CKBox.mount(document.body, {
            tokenUrl: '{{ route('ckbox_token') }}'
        });
    </script>
@endsection

```

<a id="ckbox/latest/guides/integrations/frameworks/laravel.html--complete-code">

### Complete code

On GitHub, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-laravel-example) described in this guide.

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html">source file: "ckbox/latest/guides/integrations/frameworks/nextjs.html"</a>

## Next.js

This guide describes the integration of CKBox in a Next.js application. If you prefer to jump straight to the code, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-nextjs-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--prerequisites">

### Prerequisites

Before we start, please ensure that you have a recent LTS version of Node.js installed in your system. If the tool is not available from the command line, please follow [Node.js](https://nodejs.org/en) download instructions first.

The guide assumes that we will be using Next.js v13 and its [Pages Router](https://nextjs.org/docs/pages).

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--creating-the-application">

### Creating the application

As a base in our example, we will create a new Next.js project using the `create-next-app` command. Select the following answers in the step-by-step wizard:

```
npx create-next-app@13 ckbox-nextjs-example

```

* TypeScript **Yes**
* ESLint **Yes**
* Tailwind CSS **Yes**
* `src/` directory **No**
* App Router **No**
* import alias **No**

After the project is created, you can enter the directory and start the development server:

```
cd ckbox-nextjs-example && npm run dev

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--environment-variables">

### Environment variables

First, let’s create an `.env.local` file and add the first entry: `NEXT_PUBLIC_URL=http://localhost:3000`. It will be later referenced in the `tokenUrl` configuration option of CKBox and CKEditor 5.

```
# .env.local

NEXT_PUBLIC_URL=http://localhost:3000

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--ckeditor-component-with-ckbox-plugin">

### CKEditor component with CKBox plugin

Let’s start by installing the required dependencies:

```
npm add ckbox ckeditor5 @ckeditor/ckeditor5-react

```

As of the time of writing this guide, the CKEditor React component [cannot be used with SSR](https://github.com/ckeditor/ckeditor5/issues/7376) in the Next.js project. Therefore, we will start by creating a simple component that will help us keep all editor’s dependencies in one place.

For the CKBox plugin with CKEditor 5, we will be using the `lark` theme, a built-in preset that brings CKBox and CKEditor together in terms of styling.

Below you can find the complete code. Please note that CKBox is a peer dependency of CKEditor and the latter relies on the `window.CKBox` object. We can ensure that CKBox is registered in the global scope by simply importing [CKBox UMD](#ckbox/latest/guides/integrations/frameworks/other.html--umd-file) build via `import 'ckbox/dist/ckbox'`.

```
// components/CKEditor.tsx

// This component can be used on client-side only
// Do not use it with SSR

import React from 'react';
import { CKEditor } from '@ckeditor/ckeditor5-react';
import 'ckeditor5/ckeditor5.css';
import { Bold, ClassicEditor, Italic, Underline, CKBox, PictureEditing, Autosave, BlockQuote, CKBoxImageEdit, CloudServices, Heading, List, ImageBlock, LinkImage, ImageCaption, ImageInline, ImageInsertViaUrl, Link, ImageStyle, ImageTextAlternative, ImageUpload, ImageInsert, AutoImage, Autoformat, TextTransformation } from 'ckeditor5';
import 'ckbox/dist/styles/themes/lark.css';

// CKBox is a peer dependency of CKEditor. It must be present in the global scope.
// Importing UMD build of CKBox will make sure that `window.CKBox` will be available.
import 'ckbox/dist/ckbox';

export default function CKEditorComponent() {
    const config = {
        licenseKey: 'GPL',
        ckbox: {
            tokenUrl: `${process.env.NEXT_PUBLIC_URL}/api/ckbox`,
            theme: 'lark'
        },
        toolbar: [
            'ckbox',
            'imageUpload',
            '|',
            'heading',
            '|',
            'undo',
            'redo',
            'bold',
            'italic',
            'underline',
            '|',
            'blockQuote',
            'indent',
            'link',
            'insertImage',
            '|',
            'bulletedList',
            'numberedList'
        ],
        plugins: [
            Autoformat,
            AutoImage,
            Autosave,
            BlockQuote,
            Bold,
            CKBox,
            CKBoxImageEdit,
            CloudServices,
            Heading,
            ImageBlock,
            ImageCaption,
            ImageInline,
            ImageInsert,
            ImageInsertViaUrl,
            ImageStyle,
            ImageTextAlternative,
            ImageUpload,
            Italic,
            Link,
            LinkImage,
            List,
            PictureEditing,
            TextTransformation,
            Underline
        ],
    };

    return (
        <>
            <style>{`.ck-editor__editable_inline { min-height: 400px; }`}</style>
            <CKEditor editor={ClassicEditor} config={config} />
        </>
    );
}

```

The above example includes a [predefined CKEditor 5 build](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/predefined-builds.html), which contains the required [CKBox plugin](#ckeditor5/latest/features/file-management/ckbox.html--installation). Note that CKEditor is configured to use CKBox by setting the required parameters of the `ckbox` property. Please note that in the `ckbox.tokenUrl` configuration option we pass the URL of the token endpoint that will be created in the next steps of this guide.

Finally, let’s disable React’s Strict Mode since it is interfering with the CKEditor 5 React component in development mode.

```
// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
    reactStrictMode: false,
};

module.exports = nextConfig;

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--ui-components">

### UI components

Let’s continue by creating a few UI components that we will be using across pages. In addition to re-usability, these components will bring a nicer look and feel to our app.

First, let’s update the `styles/globals.css` file. We will get rid of styling introduced by the `create-next-app` command and we will only leave Tailwind’s directives:

```
/* styles/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

```

Then, let’s add the `Button`, `Link`, and `Page` components.

```
// components/Button.tsx

import React from "react";

type Props = {
    children: React.ReactNode;
    onClick: () => void;
};

export default function Button({ children, onClick }: Props) {
    return (
        <button
            className="text-white bg-blue-600 hover:bg-blue-700 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-4 py-1.5"
            onClick={onClick}
        >
            {children}
        </button>
    );
}

```

```
// components/Link.tsx

import React from "react";
import NextLink, { type LinkProps } from "next/link";

export default function Link(
    props: Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof LinkProps> &
        LinkProps & {
            children?: React.ReactNode;
        } & React.RefAttributes<HTMLAnchorElement>
) {
    return <NextLink className="text-blue-600 dark:text-blue-500 hover:underline" {...props} />;
}

```

```
// components/Page.tsx

import React from "react";

type Props = {
    children: React.ReactNode;
};

export default function Page({ children }: Props) {
    return <main className="w-full max-w-4xl mx-auto py-16 h-full flex flex-col">{children}</main>;
}

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--authentication">

### Authentication

In a typical scenario access to CKBox will be restricted to [authenticated](#ckbox/latest/guides/configuration/authentication.html) users only. Therefore, let’s introduce a simple authentication mechanism to our app. Let’s start by installing [NextAuth.js](https://next-auth.js.org/), a popular authentication library for Next.js:

```
npm add next-auth

```

Then, let’s initialize API routes. We will be using `CredentialsProvider` which will allow us to introduce a simple password-based authentication. We will be using 3 test users and each one of them will be assigned a different CKBox role: `user`, `admin`, or `superadmin`.

Below you can find the complete code for authentication handlers.

```
// pages/api/auth/[...nextauth].ts

import NextAuth from "next-auth/next";
import CredentialsProvider from "next-auth/providers/credentials";
import type { AuthOptions, User } from "next-auth";

const dbUsers: (User & { password: string })[] = [
    {
        id: "1",
        role: "user",
        email: "user@acme.com",
        password: "testpwd123",
        name: "John",
    },
    {
        id: "2",
        role: "admin",
        email: "admin@acme.com",
        password: "testpwd123",
        name: "Joe",
    },
    {
        id: "3",
        role: "superadmin",
        email: "superadmin@acme.com",
        password: "testpwd123",
        name: "Alice",
    },
];

export const authOptions: AuthOptions = {
    providers: [
        CredentialsProvider({
            credentials: {
                email: {
                    label: "Email",
                },
                password: {
                    label: "Password",
                },
            },
            authorize: (credentials) => {
                const email = credentials?.email;
                const password = credentials?.password;

                const dbUser = dbUsers.find(
                    (dbUser) => dbUser.email === email && dbUser.password === password
                );

                if (!dbUser) {
                    throw new Error("Auth: Provide correct email and password");
                }

                return {
                    id: dbUser.email,
                    email: dbUser.email,
                    name: dbUser.name,
                    role: dbUser.role,
                };
            },
        }),
    ],
    callbacks: {
        jwt: ({ token, user }) => {
            if (user) {
                token.user = user;
            }

            return token;
        },
        session: ({ token, session }) => {
            session.user = token.user;

            return session;
        },
    },
};

export default NextAuth(authOptions);

```

The authentication library expects us to set a couple of environment variables, namely `NEXTAUTH_URL` and `NEXTAUTH_SECRET`. Let’s add them to the `.env.local` file:

```
# .env.local

# Already set
NEXT_PUBLIC_URL=http://localhost:3000

# Added now
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=G4JLoUae5Nke7/CZBkzFsR5NzLDKCcijsyUhTq3fQrA=

```

In production, you must generate your unique value for `NEXTAUTH_SECRET`, see [NextAuth’s documentation](https://next-auth.js.org/configuration/options#secret).

At this point, you are likely seeing type errors in the `[...nextauth].ts` file. In order to get rid of them, we must adjust NextAuth’s types as per the library’s [official guide](https://next-auth.js.org/getting-started/typescript). This step will allow us to use custom typings for `Session`, `User`, and `JWT` objects. Let’s create `auth.d.ts` file in the project’s root:

```
// auth.d.ts

import NextAuth, { DefaultSession } from "next-auth";

declare module "next-auth" {
    type CKBoxRole = "user" | "admin" | "superadmin";

    interface User {
        email: string;
        name: string;
        role: CKBoxRole;
    }

    interface Session {
        user: User & DefaultSession["user"];
    }
}

declare module "next-auth/jwt" {
    interface JWT {
        user: User;
    }
}

```

Next, let’s augment the main `App` component with NextAuth’s session provider.

```
// pages/_app.tsx

import { SessionProvider } from "next-auth/react";
import type { AppProps } from "next/app";
import "@/styles/globals.css";

function App({ Component, pageProps: { session, ...pageProps } }: AppProps) {
    return (
        <SessionProvider session={session}>
            <Component {...pageProps} />
        </SessionProvider>
    );
}

export default App;

```

Finally, let’s add the `Nav` component that will allow users to sign in.

```
// components/Nav.tsx

import React from "react";
import { signIn, signOut, useSession } from "next-auth/react";
import Link from "./Link";
import Button from "./Button";

export default function Nav() {
    const { data, status } = useSession();

    return (
        <nav className="border-b border-gray-200 py-5 relative z-20 bg-background shadow-[0_0_15px_0_rgb(0,0,0,0.1)]">
            <div className="flex items-center lg:px-6 px-8 mx-auto max-w-7xl">
                <div className="flex-1 hidden md:flex">
                    <Link href="/">Home</Link>
                </div>
                <div className="flex-1 justify-end flex items-center md:flex gap-3 h-8">
                    {status === "authenticated" ? (
                        <>
                            <span>Welcome, {data?.user?.name}!</span>
                            <Button onClick={() => signOut()}>Sign out</Button>
                        </>
                    ) : status === "loading" ? null : (
                        <Button onClick={() => signIn()}>Sign in</Button>
                    )}
                    <Link
                        href="https://github.com/ckbox-io/ckbox-nextjs-example"
                        target="_blank"
                        rel="noreferrer"
                    >
                        GitHub
                    </Link>
                </div>
            </div>
        </nav>
    );
}

```

The `Nav` component will be displayed as part of the `Layout` component. Let’s add it, too.

```
// components/Layout.tsx

import React from "react";
import Nav from "./Nav";

type Props = {
    children: React.ReactNode;
};

export default function Layout({ children }: Props) {
    return (
        <div className="mx-auto h-screen flex flex-col">
            <Nav />
            <div className="px-8 flex-1 bg-accents-0">{children}</div>
        </div>
    );
}

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--token-url">

### Token URL

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the [Customer Portal](https://portal.ckeditor.com). For information on how to create access credentials, please refer to the [Creating access credentials](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) article in the [Authentication guide](#ckbox/latest/guides/configuration/authentication.html)

Now that we have the required access credentials, namely: the environment ID and the access key, let’s create the token endpoint. As a base, we will use the code of the [generic token endpoint in Node.js](#cs/latest/examples/token-endpoints/nodejs.html).

First, let’s install the [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) library for creating JWT tokens:

```
npm add jsonwebtoken
npm add -D @types/jsonwebtoken

```

As a reference, we will use the code of the [generic token endpoint in Node.js](#cs/latest/examples/token-endpoints/nodejs.html). Let’s wrap the logic of the Node.js token endpoint with the Next.js API handler and generate a token with the [payload required by CKBox](#ckbox/latest/guides/configuration/authentication.html--token-payload). Please note that access to this endpoint is limited to authenticated users only.

```
// pages/api/ckbox.ts

import jwt from "jsonwebtoken";
import { getServerSession } from "next-auth";
import type { NextApiRequest, NextApiResponse } from "next";
import { authOptions } from "./auth/[...nextauth]";

const CKBOX_ENVIRONMENT_ID = process.env.CKBOX_ENVIRONMENT_ID;
const CKBOX_ACCESS_KEY = process.env.CKBOX_ACCESS_KEY;

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
    const session = await getServerSession(req, res, authOptions);

    if (session && CKBOX_ACCESS_KEY && CKBOX_ENVIRONMENT_ID) {
        const user = session.user;

        const payload = {
            aud: CKBOX_ENVIRONMENT_ID,
            sub: user.id,
            auth: {
                ckbox: {
                    role: user.role,
                },
            },
        };

        res.send(
            jwt.sign(payload, CKBOX_ACCESS_KEY, {
                algorithm: "HS256",
                expiresIn: "1h",
            })
        );
    } else {
        res.status(401);
    }

    res.end();
}

```

As you can see on the code listed above, the access credentials required to sign JWT tokens are obtained from the environment variables. Thanks to this, you can conveniently add them to the `.env.local` file:

```
# .env.local

# Already set
NEXT_PUBLIC_URL=http://localhost:3000
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=G4JLoUae5Nke7/CZBkzFsR5NzLDKCcijsyUhTq3fQrA=

# Added now
CKBOX_ENVIRONMENT_ID=REPLACE-WITH-ENVIRONMENT-ID
CKBOX_ACCESS_KEY=REPLACE-WITH-ACCESS-KEY

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--adding-ckbox-pages">

### Adding CKBox pages

CKBox can be embedded in the application in [multiple ways](#ckbox/latest/guides/installation.html). Examples in this guide will cover three popular scenarios:

* CKBox integrated with CKEditor 5
* CKBox used as a file picker in dialog mode
* CKBox used as a file manager in inline mode

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--ckbox-with-ckeditor">

#### CKBox with CKEditor

Let’s use components created in previous steps to compose the `/ckeditor` page:

```
// pages/ckeditor.tsx

import { GetServerSideProps } from "next";
import { getServerSession } from "next-auth";
import Layout from "@/components/Layout";
import Page from "@/components/Page";
import { authOptions } from "@/pages/api/auth/[...nextauth]";
import dynamic from "next/dynamic";

// Use client-side rendering for CKEditor component
const CKEditor = dynamic(() => import("@/components/CKEditor").then((e) => e.default), {
    ssr: false,
});

export default function CKEditorPage() {
    return (
        <Layout>
            <Page>
                <section className="flex flex-col gap-6">
                    <h2 className="text-4xl font-semibold tracking-tight">CKEditor</h2>
                </section>
                <hr className="border-t border-accents-2 my-6" />
                <section className="flex flex-col gap-3 h-4/5">
                    In this example CKBox is integrated with CKEditor. With CKBox plugin, CKEditor
                    will upload files directly to your CKBox environment. Use icon in the top-left
                    corner of the editor to open CKBox as a file picker.
                    <CKEditor />
                </section>
            </Page>
        </Layout>
    );
}

// Access to this page allowed to signed-in users only
export const getServerSideProps: GetServerSideProps = async ({ req, res, resolvedUrl }) => {
    const session = await getServerSession(req, res, authOptions);

    if (!session) {
        return {
            redirect: {
                destination: `/api/auth/signin?callbackUrl=${encodeURIComponent(resolvedUrl)}`,
                permanent: false,
            },
        };
    }

    return {
        props: {
            session,
        },
    };
};

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--ckbox-as-file-picker">

#### CKBox as file picker

One of the common scenarios is to use CKBox as a file picker, where the user can choose one of the files stored in the file manager. After choosing the file, we want to obtain information about the chosen files, especially their URLs. This can be achieved using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback passed as the CKBox’s configuration option.

In Next.js we can use CKBox directly as a React component. Currently, however, the `CKBox` official component cannot be rendered on the server. Therefore, we must ensure that it’s used on the client side only.

Let’s start by installing the required packages:

```
npm add @ckbox/core @ckbox/components

```

The complete page code can be found below.

```
// pages/file-picker.tsx

import React from 'react';
import { GetServerSideProps } from 'next';
import dynamic from 'next/dynamic';
import { getServerSession } from 'next-auth';
import type { Asset, Props } from '@ckbox/core';
import Layout from '@/components/Layout';
import Page from '@/components/Page';
import Button from '@/components/Button';
import Link from '@/components/Link';
import { authOptions } from '@/pages/api/auth/[...nextauth]';

// CKBox cannot be currently rendered on the server
const CKBox = dynamic(() => import('@ckbox/core').then((e) => e.CKBox), {
    ssr: false
});

// Let's import stylesheet separately, since it's not bundled with the official React component
import '@ckbox/components/dist/styles/ckbox.css';

export default function FilePicker() {
    const [assets, setAssets] = React.useState<Asset[]>([]);
    const [open, setOpen] = React.useState(false);

    const handleOpen = () => {
        setOpen(true);
    };

    const handleClose = () => {
        setOpen(false);
    };

    const handleChoose = (assets: Asset[]) => {
        setOpen(false);
        setAssets(assets);
    };

    const ckboxProps: Props = {
        assets: { onChoose: handleChoose },
        dialog: { open, onClose: handleClose },
        tokenUrl: `${process.env.NEXT_PUBLIC_URL}/api/ckbox`
    };

    return (
        <Layout>
            <Page>
                <section className="flex flex-col gap-6">
                    <h2 className="text-4xl font-semibold tracking-tight">
                        File Picker
                    </h2>
                </section>
                <hr className="border-t border-accents-2 my-6" />
                <section className="flex flex-col gap-3">
                    One of the common scenarios is to use CKBox as a file
                    picker, where the user can choose one of the files stored in
                    the file manager. After choosing the file, we want to obtain
                    information about the chosen files, especially their URLs.
                    <div>
                        <Button onClick={handleOpen}>Choose assets</Button>
                    </div>
                    <CKBox {...ckboxProps} />
                </section>
                <section className="flex flex-col gap-3">
                    <ul>
                        {assets.map(({ data }) => {
                            const name = `${data.name}.${data.extension}`;
                            const content = data.url ? (
                                <Link
                                    target="_blank"
                                    rel="noreferrer"
                                    href={data.url}
                                >
                                    {name}
                                </Link>
                            ) : (
                                name
                            );

                            return <li key={data.id}>{content}</li>;
                        })}
                    </ul>
                </section>
            </Page>
        </Layout>
    );
}

// Access to this page allowed to signed-in users only
export const getServerSideProps: GetServerSideProps = async ({
    req,
    res,
    resolvedUrl
}) => {
    const session = await getServerSession(req, res, authOptions);

    if (!session) {
        return {
            redirect: {
                destination: `/api/auth/signin?callbackUrl=${encodeURIComponent(
                    resolvedUrl
                )}`,
                permanent: false
            }
        };
    }

    return {
        props: {
            session
        }
    };
};

```

At this point, it’s also important to adjust the Webpack config of Next.js. We must ensure that `@ckbox/*` dependencies are not code-split. Below is the complete `next.config.js` file.

```
// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
    reactStrictMode: false,
    webpack: (config, options) => {
        if (!options.isServer) {
            config.optimization.splitChunks.cacheGroups = {
                ...config.optimization.splitChunks.cacheGroups,
                ckbox: {
                    test: /@ckbox\//,
                    minChunks: 1,
                    priority: 50,
                },
            };
        }

        return config;
    },
};

module.exports = nextConfig;

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--ckbox-in-inline-mode">

#### CKBox in inline mode

To start CKBox in inline mode, you can simply mount it in the desired place of your app. This is the default embedding mode for CKBox, so no additional configuration props besides `tokenUrl` are required. CKBox will occupy as much space as allowed by its parent element.

```
// pages/inline.tsx

import { GetServerSideProps } from "next";
import { getServerSession } from "next-auth";
import dynamic from "next/dynamic";
import Layout from "@/components/Layout";
import Page from "@/components/Page";
import { authOptions } from "@/pages/api/auth/[...nextauth]";

// CKBox cannot be currently rendered on the server
const CKBox = dynamic(() => import("@ckbox/core").then((e) => e.CKBox), {
    ssr: false,
});

// Let's import stylesheet separately, since it's not bundled with the React component
import "@ckbox/components/dist/styles/ckbox.css";

export default function Inline() {
    return (
        <Layout>
            <Page>
                <section className="flex flex-col gap-6">
                    <h2 className="text-4xl font-semibold tracking-tight">Inline</h2>
                </section>
                <hr className="border-t border-accents-2 my-6" />
                <section className="flex flex-col gap-3 flex-1">
                    <p>
                        To start CKBox in inline mode, you can instantiate it in an arbitrary
                        container. CKBox will respect height and width of the container.
                    </p>
                    <CKBox tokenUrl={`${process.env.NEXT_PUBLIC_URL}/api/ckbox`} />
                </section>
            </Page>
        </Layout>
    );
}

// Access to this page allowed to signed-in users only
export const getServerSideProps: GetServerSideProps = async ({ req, res, resolvedUrl }) => {
    const session = await getServerSession(req, res, authOptions);

    if (!session) {
        return {
            redirect: {
                destination: `/api/auth/signin?callbackUrl=${encodeURIComponent(resolvedUrl)}`,
                permanent: false,
            },
        };
    }

    return {
        props: {
            session,
        },
    };
};

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--home-page">

### Home page

Finally, let’s tweak the home page so that it displays links to all pages created above.

```
// pages/index.tsx

import Layout from "@/components/Layout";
import Link from "@/components/Link";
import Page from "@/components/Page";

export default function Home() {
    return (
        <Layout>
            <Page>
                <section className="flex flex-col gap-6">
                    <h2 className="text-3xl font-semibold tracking-tight">
                        CKBox integration with Next.js
                    </h2>
                </section>
                <hr className="border-t border-accents-2 my-6" />
                <section className="flex flex-col gap-3">
                    <p>Below you can find example integrations of CKBox.</p>
                    <p>
                        In a typical scenario access to CKBox will be restricted to authenticated
                        users only. Therefore, each sample is restricted to signed in users only.
                        Use different credentials to unlock various CKBox roles. See available users{" "}
                        <Link
                            href="https://github.com/ckbox-io/ckbox-nextjs-example/blob/main/pages/api/auth/%5B...nextauth%5D.ts"
                            target="_blank"
                            rel="noreferrer"
                        >
                            here
                        </Link>
                        .
                    </p>
                    <div className="flex-1 hidden md:flex gap-2">
                        <ol>
                            <li>
                                <Link href="/inline">Inline mode</Link>
                            </li>
                            <li>
                                <Link href="/file-picker">File picker</Link>
                            </li>
                            <li>
                                <Link href="/ckeditor">CKEditor</Link>
                            </li>
                        </ol>
                    </div>
                </section>
            </Page>
        </Layout>
    );
}

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--congratulations">

### Congratulations

Congratulations on completing the guide! You can now access the app in development mode:

```
npm run dev

```

Or use the production build:

```
npm run build && npm start

```

<a id="ckbox/latest/guides/integrations/frameworks/nextjs.html--complete-code">

### Complete code

On GitHub, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-nextjs-example) described in this guide.

<a id="ckbox/latest/guides/integrations/frameworks/other.html">source file: "ckbox/latest/guides/integrations/frameworks/other.html"</a>

## Other

There are no limitations as to front-end frameworks with which CKBox can be integrated. Following code snippets will help you use it with any technology.

<a id="ckbox/latest/guides/integrations/frameworks/other.html--ecmascript-export">

### ECMAScript export

Import `CKBox` by using named import syntax of ECMAScript modules. Mount an instance of CKBox by providing a reference to a DOM element.

```
import * as CKBox from "ckbox";
import "ckbox/dist/styles/ckbox.css";

const app = document.querySelector("#app");

const { unmount } = CKBox.mount(app, {
    dialog: true,
    tokenUrl: "https://your.token.url",
});

// A cleanup function invoked at some point in the client app's lifecycle.
function cleanup() {
    // Unmount CKBox instance if it's not needed anymore.
    // Note that CKBox will unmount automagically on closing the dialog or on choosing an asset.
    unmount();
}

```

<a id="ckbox/latest/guides/integrations/frameworks/other.html--umd-file">

### UMD file

CKBox UMD file is a standalone, batteries-included build. It contains all necessary dependencies and the default styling. While typically UMD builds are referenced directly in `script` elements as [shown here](#ckbox/latest/guides/quick-start.html--cdn), they can be as well used in other scenarios, e.g. when using ECMAScript modules.

Import UMD build only once in your app. As a result, `CKBox` will be exposed on the global object. Create an instance of CKBox by providing a reference to a DOM element.

```
// There is no need to import stylesheet separately when using UMD build.
// Import this file only once in your app.
import "ckbox/dist/ckbox.js";

const app = document.querySelector("#app");

// `CKBox` is available globally.
CKBox.mount(app, {
    dialog: true,
    tokenUrl: "https://your.token.url",
});

```

<a id="ckbox/latest/guides/integrations/frameworks/react-integration.html">source file: "ckbox/latest/guides/integrations/frameworks/react-integration.html"</a>

## React

If you would like to use CKBox in a React application, you can directly use the `CKBox` React component exported by the `@ckbox/core` package. Start by installing the following packages with NPM or an equivalent tool:

```
npm install @ckbox/core @ckbox/components

```

If you use CKEditor plugin for CKBox, then additionally install `ckbox` package:

```
npm install ckbox

```

Shown below is the content of an example React component file:

```
import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

// CKEditor plugin for CKBox has an implicit dependency on `ckbox` package.
// Therefore, make sure to install and import it if you use the plugin.
//
// If you don't use CKEditor plugin for CKBox, then `ckbox` package can be omitted.
import "ckbox";

function App() {
    return <CKBox tokenUrl="https://your.token.url" />;
}

export default App;

```

<a id="ckbox/latest/guides/integrations/frameworks/react-integration.html--category-icons-as-react-components">

### Category icons as React components

When using React, you can easily override the category icons with custom React components in addition to using [icons as plain strings](#ckbox/latest/guides/configuration/configuration-options.html--categoriesicons). CKBox styling is injected via the `className` prop.

```
import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

function App() {
    return (
        <CKBox
            categories={{
                icons: {
                    Files: ({ className }) => (
                        <svg
                            xmlns="http://www.w3.org/2000/svg"
                            className={className}
                            viewBox="0 0 20 20"
                        >
                            <path d="M6 6V5a3 3 0 013-3h2a3 3 0 013 3v1h2a2 2 0 012 2v3.57A22.952 22.952 0 0110 13a22.95 22.95 0 01-8-1.43V8a2 2 0 012-2h2zm2-1a1 1 0 011-1h2a1 1 0 011 1v1H8V5zm1 5a1 1 0 011-1h.01a1 1 0 110 2H10a1 1 0 01-1-1z" />
                            <path d="M2 13.692V16a2 2 0 002 2h12a2 2 0 002-2v-2.308A24.974 24.974 0 0110 15c-2.796 0-5.487-.46-8-1.308z" />
                        </svg>
                    ),
                },
            }}
            tokenUrl="https://your.token.url"
        />
    );
}

export default App;

```

<a id="ckbox/latest/guides/integrations/frameworks/react-integration.html--legacy-versions-of-react">

### Legacy versions of React

As noted above, `@ckbox/core` package requires React 18 to work correctly and it cannot be used directly with legacy versions of React.

Therefore, if your app is using a pre-18 version of React, then we advise you to use `ckbox` package instead. Since `react` and `react-dom` are transitive dependencies of `ckbox` package, then its UMD build should be used to avoid issues with running multiple versions of React in the same app.

Start by importing `ckbox` UMD build in your app’s entry file:

```
import React from "react";
import ReactDOM from "react-dom";
import App from "./App";

// Import UMD build only once in your app.
// `CKBox` object will be exposed globally.
import "ckbox/dist/ckbox.js";

const app = document.getElementById("app");

ReactDOM.render(
    <React.StrictMode>
        <App />
    </React.StrictMode>,
    app
);

```

`CKBox` object will be exposed globally, so it can be referenced later in components without a direct import:

```
import React from "react";

function App() {
    const ref = React.useRef(null);

    React.useEffect(() => {
        const root = ref.current;

        if (!root) {
            return;
        }

        const { unmount } = CKBox.mount(root, {
            dialog: true,
            tokenUrl: "https://your.token.url",
        });

        return () => {
            unmount();
        };
    }, []);

    return <div ref={ref} />;
}

export default App;

```

<a id="ckbox/latest/guides/integrations/frameworks/react-integration.html--server-side-rendering">

### Server-side rendering

While in theory CKBox can be rendered on the server-side, it still relies on client-side features such as [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) during instantation. This might lead to a mismatch between HTML rendered on the server side and the one on the client side, resulting in poorer user experience. Therefore, if your app is using server-side rendering by default, then we advise to opt-out of that feature for CKBox.

<a id="ckbox/latest/guides/integrations/frameworks/react-integration.html--nextjs">

#### Next.js

[Next.js](https://nextjs.org/) is one of the most popular React frameworks that employs server-side rendering by default. You can easily integrate CKBox with Next.js by importing it dynamically with **disabled SSR** as shown below:

```
import React from "react";
import dynamic from "next/dynamic";
import "@ckbox/components/dist/styles/ckbox.css";

const CKBox = dynamic(() => import("@ckbox/core").then((e) => e.CKBox), {
    ssr: false,
});

export default function Home() {
    return <CKBox dialog={true} tokenUrl="https://your.token.url" />;
}

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html">source file: "ckbox/latest/guides/integrations/frameworks/spring-boot.html"</a>

## Spring Boot

This guide describes the integration of CKBox in a Spring Boot application. If you prefer to jump straight to the code, you can find the [complete code of the application](https://github.com/ckbox-io/ckbox-spring-boot-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--prerequisites">

### Prerequisites

Before we start, please ensure that you have a recent version of JDK installed in your system. If the tool is not available from the command line, please follow the [JDK installation instructions](https://www.oracle.com/java/technologies/downloads/) first.

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--creating-the-application">

### Creating the application

As a base in our example, we will create a new Spring Boot project using the [Spring Initializr](https://start.spring.io/) wizard. The examples in this document will use Maven. If you want to follow this guide step-by-step, set your project type to “Maven”. You can also use a different project type by replacing commands and configurations with equivalent ones in other tools.

Parameters used to create the project in this guide:

* Group: `io.ckbox`
* Artifact: `spring-example`
* Name: `spring-example`
* Project: `Maven`
* Language: `Java`
* Dependencies: **Spring Web**

After the project is created, start the development server:

```
./mvnw spring-boot:run

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--creating-the-authorization-controller">

### Creating the authorization controller

First, let’s create a controller. The controller will be responsible for serving the token endpoint, used to authenticate users in CKBox.

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the [Customer Portal](https://portal.ckeditor.com). For information on how to create access credentials, please refer to the [Creating access credentials](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) section in the [Authentication](#ckbox/latest/guides/configuration/authentication.html) guide.

Now that we have the required access credentials, namely: the environment ID and the access key, let’s create the token endpoint.

First, let’s add the `com.auth0.jwt` library for creating JWT tokens to `pom.xml` file:

```
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>4.4.0</version>
</dependency>

```

The dependency will be installed upon the next application start.

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--complete-controller-code">

#### Complete controller code

```
// src/main/java/io/ckbox/springexample/CKBoxController.java

package io.ckbox.springexample;

import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

import org.springframework.beans.factory.annotation.*;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;

import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.JWT;

@RestController
public class CKBoxController {
    @Value("${environment_id}")
    private String environmentId;

    @Value("${access_key}")
    private String accessKey;

    @GetMapping("/ckbox/auth")
    public String tokenEndpoint() throws Exception {
        Map<String, Object> authClaim = new HashMap<>() {{
            put("ckbox", new HashMap<>() {{
                put("role", "user");
            }});
        }};

        Algorithm algorithm = Algorithm.HMAC256(this.accessKey.getBytes("ASCII"));

        String token = JWT.create()
            .withAudience(this.environmentId)
            .withIssuedAt(Instant.now())
            .withSubject("user id")
            .withClaim("auth", authClaim)
            .sign(algorithm);

        return token;
    }
}

```

As you can see on the code listing above, the access credentials required to sign JWT tokens are obtained from the environment variables. Now, you can run the application with:

```
environment_id=REPLACE-WITH-ENVIRONMENT-ID access_key=REPLACE-WITH-ACCESS-KEY ./mvnw spring-boot:run

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--adding-ckbox-script-to-the-page">

### Adding CKBox script to the page

CKBox can be embedded in the application in [multiple ways](#ckbox/latest/guides/installation.html). We will use the CKBox script served from the CDN for simplicity.

Examples in this guide will cover three popular scenarios of using CKBox:

* CKBox integrated with CKEditor 5.
* CKBox used as a file picker in dialog mode.
* CKBox used as a full-page application.

To avoid code repetition, let’s prepare a base Thymeleaf layout template that includes the CKBox script, which we will reuse in all three examples. First, add Thymeleaf dependencies to the `pom.xml` file:

```
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<dependency>
    <groupId>nz.net.ultraq.thymeleaf</groupId>
    <artifactId>thymeleaf-layout-dialect</artifactId>
</dependency>

```

Then you can create a layout file:

```
<!-- src/main/resources/templates/layout.html -->
<!DOCTYPE html>
<html xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout">
<html>
<head>
    <meta charset="UTF-8"/>
    <title>CKBox example</title>
    <script src="https://cdn.ckbox.io/ckbox/2.1.0/ckbox.js"></script>
</head>
<body>
    <section layout:fragment="content">
        <p>Page content goes here</p>
    </section>
</body>
</html>

```

Finally, prepare an MVP controller for the examples:

```
// src/main/java/io/ckbox/springexample/CKBoxExampleWebpageController.java
package io.ckbox.springexample;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;

@Controller
public class CKBoxExampleWebpageController {
}

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--ckbox-with-ckeditor-5">

#### CKBox with CKEditor 5

In this example, we will use the quickest and easiest way to run CKEditor 5 – served from the CDN. For more advanced integration scenarios, please refer to the [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/installation/index.html).

Let’s create the child view that extends the layout we have created in the previous step:

```
<!-- src/main/resources/templates/ckbox-example-ckeditor.html -->
<!DOCTYPE html>
<html xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
    layout:decorate="~{layout}">
<head>
    <script type="importmap">
        {
            "imports": {
                "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.js",
                "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/48.0.0/"
            }
        }
    </script>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
</head>
<body>
    <section layout:fragment="content">
        <textarea id="editor"><h1>Example</h1><p>Hello world</p></textarea>

        <script type="module">
            import {
                ClassicEditor,
                CKBox,
                Essentials,
                Bold,
                Italic,
                Font,
                Paragraph
            } from 'ckeditor5';

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    plugins: [ CKBox, Essentials, Bold, Italic, Font, Paragraph ],
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'lark',
            allowExternalImagesEditing: [ /^data:/, 'origin', /ckbox/ ]
                    },
                    toolbar: [
                        'ckbox', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </section>
</body>
</html>

```

and add the view to the controller:

```
@Controller
public class CKBoxExampleWebpageController {
    @GetMapping("/ckbox-example-ckeditor")
    public String ckeditorExample(Model model) {
        return "ckbox-example-ckeditor";
    }
}

```

The above example includes a [predefined CKEditor 5 build](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/predefined-builds.html) from the CDN, which includes the required [CKBox plugin](#ckeditor5/latest/features/file-management/ckbox.html--installation). Then, CKEditor 5 is configured to use CKBox by setting the required parameters of the `ckbox` attribute. Please note that in the `ckbox.tokenUrl` configuration option we pass the URL of the token endpoint created in one of the previous steps. It will be used to obtain JWT tokens used to authenticate users in CKBox.

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--ckbox-as-file-picker">

#### CKBox as file picker

One of the common scenarios is to use CKBox as a file picker, where the user can choose one of the files stored in the file manager. After choosing the file, we want to obtain information about the chosen files, especially their URLs. This can be achieved using the [assets.onChoose](#ckbox/latest/guides/configuration/configuration-options.html--assetsonchoose) callback passed as the CKBox’s configuration option:

```
<!-- src/main/resources/templates/ckbox-example-modal.html -->
<!DOCTYPE html>
<html xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
    layout:decorate="~{layout}">
<body>
    <section layout:fragment="content">
        <input type="text" id="file-url"></input><button id="choose">Choose file</button>
        <div id="ckbox"></div>
        <script>
            document.getElementById('choose').addEventListener('click', function () {
                CKBox.mount(document.querySelector('#ckbox'), {
                    tokenUrl: `${ location.origin }/ckbox/auth`,
                    dialog: true,
                    assets: {
                        // Callback executed after choosing assets
                        onChoose: (assets) => {
                            document.getElementById('file-url').value = assets[0].data.url;

                            assets.forEach((asset) => {
                                console.log(asset.data.url);
                            })
                        }
                    }
                });
            });
        </script>
    </section>
</body>
</html>


```

```
@Controller
public class CKBoxExampleWebpageController {
    // ...

    @GetMapping("/ckbox-example-modal")
    public String modalExample(Model model) {
        return "ckbox-example-modal";
    }
}

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--ckbox-in-full-page-mode">

#### CKBox in full-page mode

To start CKBox in full-page mode, you can attach it to the `document.body` and adjust the required CSS styles:

```
<!-- src/main/resources/templates/ckbox-example-full-page.html -->
<!DOCTYPE html>
<html xmlns:layout="http://www.ultraq.net.nz/thymeleaf/layout"
    layout:decorate="~{layout}">
    <style>
        html, body {
            margin: 0;
            padding: 0;
            height: 100vh;
        }
    </style>
<body>
    <section layout:fragment="content">
        <script>
            CKBox.mount(document.body, {
                tokenUrl: `${ location.origin }/ckbox/auth`
            });
        </script>
    </section>
</body>
</html>

```

```
@Controller
public class CKBoxExampleWebpageController {
    // ...

    @GetMapping("/ckbox-example-full-page")
    public String fullPageExample(Model model) {
        return "ckbox-example-full-page";
    }
}

```

<a id="ckbox/latest/guides/integrations/frameworks/spring-boot.html--complete-code">

### Complete code

You can find the [complete code of the application](https://github.com/ckbox-io/ckbox-spring-boot-example) described in this guide on GitHub.

<a id="ckbox/latest/guides/integrations/frameworks/vue-integration.html">source file: "ckbox/latest/guides/integrations/frameworks/vue-integration.html"</a>

## Vue

If you would like to use CKBox in a Vue application, start by installing the `ckbox` package as described in [this guide](#ckbox/latest/guides/installation.html--npm). Then, create a Vue component in which you attach a reference to a `<div />` element and use it to instantiate CKBox in the `onMounted` lifecycle method.

Show below is the content of an example Vue component file:

```
<template>
    <div ref="ckbox" />
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue";
import * as CKBox from "ckbox";
import "ckbox/dist/styles/ckbox.css";

const ckbox = ref();

onMounted(() => {
    CKBox.mount(ckbox.value, {
        tokenUrl: "https://your.token.url",
    });
});
</script>

```

<a id="ckbox/latest/guides/integrations/webpack-integration.html">source file: "ckbox/latest/guides/integrations/webpack-integration.html"</a>

## Webpack

If you would like to use CKBox with webpack, start by installing the `ckbox` package along with the necessary webpack packages, and loaders.

```
npm i ckbox
npm i -D webpack webpack-cli css-loader style-loader ts-loader typescript html-webpack-plugin

```

<a id="ckbox/latest/guides/integrations/webpack-integration.html--prepare-entry-point-file">

#### Prepare entry point file

Import CKBox dependency in the desired location, and add CSS styling file import required by CKBox components.  
Shown below is the content of an example entry file:

```
import * as CKBox from 'ckbox';
import 'ckbox/dist/styles/ckbox.css';

const app = document.querySelector<HTMLDivElement>('#app');

if (!app) {
    throw new Error('Missing #app element');
}

CKBox.mount(app, {
    dialog: true,
    tokenUrl: 'https://your.token.url'
});

```

<a id="ckbox/latest/guides/integrations/webpack-integration.html--prepare-template-html-file">

#### Prepare template HTML file

Place the following snippet inside the html template file:

```
<div id="ckbox"></div>

```

<a id="ckbox/latest/guides/integrations/webpack-integration.html--configure-webpack">

#### Configure webpack

To get CKBox up and running, at first you need to instruct webpack how it should treat TypeScript files and how to transform styling css files. Use `ts-loader` or a similar loader to transpile TypeScript to JavaScript. Additionally, use `style-loader` \+ `css-loader` or similar to transform `.css` files.

```
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
    entry: './src/main.tsx',
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                use: 'ts-loader',
                exclude: /node_modules/,
            },
            {
                test: /\.css$/i,
                use: ['style-loader', 'css-loader'],
            },
        ],
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js'],
    },
    output: {
        filename: 'main.js',
        path: path.resolve(__dirname, 'dist'),
    },
    plugins: [new HtmlWebpackPlugin({
        template: path.resolve(__dirname, 'index.html'),
    })],
    mode: 'development',
    ...
};

```

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html">source file: "ckbox/latest/guides/migration/ckbox-migrator-tool.html"</a>

## CKBox Migration Tool

This guide will show you how to transfer assets from your old system like CKFinder or Easy Image to CKBox. You will also find information on how to replace the old URLs in your system with CKBox links after the migration.

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--using-the-migration-tool">

### Using the Migration Tool

The Migration Tool is a CLI application designed to migrate your assets between systems. It has built-in support for Easy Image and CKFinder, and you can also create a custom adapter to migrate files from any source.

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--installation">

### Installation

Before installing the Migration Tool, ensure that you have NodeJS version 18.x or later installed. For instructions on installing NodeJS, visit [this page](https://nodejs.org/en/download/package-manager).

You can then download and build the Migration Tool from source:

```
git clone git@github.com:ckbox-io/migration-tool.git
cd migration-tool
npm install
npm run build

```

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--preparing-the-migration">

### Preparing the migration

In order to migrate your assets, you will need to configure a connection to your source storage and to the CKBox. First, prepare the configuration of the CKBox connection.

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--configuration-of-ckbox-connection">

### Configuration of CKBox connection

Create a `config.json` file in the directory where you downloaded the migrator tool. You can copy and use `config.template.json` as a template for your own configuration.

You will need to provide the access credentials (namely the environment ID and access key). You can read more about CKBox credentials in the [Authentication](#ckbox/latest/guides/configuration/authentication.html--creating-access-credentials) guide. You should also provide the `serviceOrigin` URL. If you are a SaaS client, it should point to `https://api.ckbox.io`. For the on-premises version, you need to set this value to the URL pointing to the REST API of your CKBox On-Premises application.

```
{
    "ckbox": {
        "accessCredentials": {
            "environmentId": "<ENVIRONMENT_ID>",
            "accessKey": "<ACCESS_KEY>"
        },
        "workspaceId": "<WORKSPACE_ID>",
        "serviceOrigin": "<SERVICE_ORIGIN>"
    }
}

```

Optionally, you can also specify a `workspaceId`. If you do not, all files will be uploaded to a default workspace. Read more about workspaces in the [Workspaces](#ckbox/latest/features/file-management/workspaces.html) guide.

**List of configuration options for CKBox connection**

| Option name                           | Description                                    |
| ------------------------------------- | ---------------------------------------------- |
| ckbox.assetsCredentials.environmentId | Target environment for the migration.          |
| ckbox.assetsCredentials.accessKey     | Access Key used to sign authorization token.   |
| ckbox.workspaceId                     | Target workspace for the migration (optional). |
| ckbox.serviceOrigin                   | Sets the origin to use for the CKBox REST API. |

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--preparing-the-source-storage">

### Preparing the source storage

The source storage configuration depends on the type of system you are migrating from. If you are migrating from CKFinder or Easy Image, you can use the built-in support and use the examples below. For other systems, you will need to implement your own `SourceStorageAdapter`. More information about migrating from custom storage can be found in [this article](#ckbox/latest/guides/migration/migration-from-custom-sources.html).

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--ckfinder">

#### CKFinder

To migrate assets from CKFinder, you must set a `type` for `ckfinder`, set the URL to the connector, and add the headers used for authentication.

```
{
    "source": {
        "type": "ckfinder",
        "options": {
            "connectorPath": "http://localhost:8080/ckfinder/connector",
            "authentication": {
                "headers": {
                    "Cookie": "PHPSESSID=e0baf7e705e40f7e7dea7fa3d04a5a79"
                }
            }
        }
    },
    "ckbox": {
        ...
    }
}

```

**List of configuration options for CKFinder connection**

| Option name                           | Description                                       |
| ------------------------------------- | ------------------------------------------------- |
| source.type                           | Must be set to ckfinder.                          |
| source.options.connectorPath          | Sets the origin to use for the CKFinder REST API. |
| source.options.authentication.headers | Sets headers needed for authentication.           |

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--easy-image">

#### Easy Image

To migrate assets from Easy Image, you must set the `type` to `easy-image`, set the REST API origin URL, and add access credentials.

You can find more about Easy Image credentials in the [CKEditor Cloud Services authorization](#cs/latest/developer-resources/security/access-key.html--managing-the-access-credentials) guide.

```
{
    "source": {
        "type": "easy-image",
        "options": {
            "accessCredentials": {
                "environmentId": "<ENVIRONMENT_ID>",
                "accessKey": "<ACCESS_KEY>"
            },
            "serviceOrigin": "<SERVICE_ORIGIN>"
        }
    },
    "ckbox": {
        ...
    }
}

```

**List of configuration options for Easy Image connection**

| Option name                                    | Description                                         |
| ---------------------------------------------- | --------------------------------------------------- |
| source.type                                    | Must be set to easy-image.                          |
| source.options.assetsCredentials.environmentId | Source environment for the migration.               |
| source.options.assetsCredentials.accessKey     | Access Key used to sign authorization token.        |
| source.options.serviceOrigin                   | Sets the origin to use for the Easy Image REST API. |

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--checking-the-configuration">

### Checking the configuration

Before migration it is advisable to verify the configuration first by running the migrator in the dry run mode. This command will verify connections and scan the source storage to see if it has access to resources.

```
npm start -- --dry-run


```

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--running-the-migration">

### Running the migration

To start the migration you need to execute the command below:

```
npm start

```

This command will create categories, folders and upload assets to your CKBox instance.

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--replacing-the-old-urls-with-the-new-ones-in-your-application">

### Replacing the old URLs with the new ones in your application

Once the migration process is complete, the migrator generates a file that maps the old URLs to the new URLs. The file name will have the format `ckbox_mapped_URLs_[migration time].txt`. You can use this file to replace the old URLs with the new ones in your application.

The file contains pairs of URLs, with each pair on a new line. The URL of the source file and the migrated file are separated by a tab character.

<a id="ckbox/latest/guides/migration/ckbox-migrator-tool.html--troubleshooting">

### Troubleshooting

In the event of any issues, the migrator will generate logs in the `ckbox_migrator_[migration time].log` file. It includes comprehensive details about the issues that occurred.

You should also be aware that the migrator will try to migrate remaining resources even if one of them fails. You’ll get a message about this in the console so you can check the logs for more information. If you find that some resources failed to migrate, but others did not, you must first check and fix the problem (for example adjust permissions for the source system or CKBox). Then, you can:

* You could try uploading the failed assets manually.
* Alternatively, you could revert the migration by removing the resources from CKBox and trying the migration again.

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html">source file: "ckbox/latest/guides/migration/migration-from-custom-sources.html"</a>

## Migration from custom sources

To migrate files from custom sources, you need to create your own implementation of `SourceStorageAdapter`. The adapters prepare migration plans with the lists of categories, folders and assets to migrate. They also expose a method allowing the migrator to download files from the storage.

To create a new adapter, a directory must first be created in the `adapters/` directory.

The next step is to create the `Adapter.ts` file. This is the entry point of the adapter and you cannot change this filename. To create the file, you may use the boilerplate below:

```
import {
    ISourceStorageAdapter,
    IMigrationPlan,
    ISourceCategory,
    ISourceFolder,
    ISourceAsset
} from '@ckbox-migrator';

export default class ExampleAdapter implements ISourceStorageAdapter {
    public readonly name: string = 'The name of your system';

    public async loadConfig( plainConfig: Record<string, unknown> ): Promise<void> {
        // Load and validate configuration.
    }

    public async verifyConnection(): Promise<void> {
        // Verify if you can connect and authorize to your source storage.
    }

    public async prepareMigrationPlan(): Promise<IMigrationPlan> {
        // Scan your source storage and identify the categories,
        // folders and assets to migrate.

        return [
            categories: [],
            assets: []
        ];
    }

    public async getAsset( downloadUrl: string ): Promise<IGetAssetResult> {
        // Get an asset content from you source storage.
    }
}

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--loading-the-configuration">

### Loading the configuration

To load the configuration, you need to implement the `loadConfig( plainConfig: Record<string, unknown> )` method. It is the first step performed in the migration process. The parameter provided to the method is a `source.options` property from `config.json` file.

To validate the configuration, we recommend using the `class-validator` and `class-transformer` libraries. They are already bundled with the migrator so you do not need to install them separately.

First you need to create the configuration class. It will contain the config properties and validation rules.

```
class ExampleConfig {
    @IsString()
    @IsDefined()
    public readonly foo: string;
}

```

Then, you can map the config using the `plainToInstance` and validate it using the `validateOrReject` method.

```
export default class ExampleAdapter implements ISourceStorageAdapter {

    // ...

    private _config: ExampleConfig;

    public async loadConfig( plainConfig: Record<string, unknown> ): Promise<void> {
        this._config = plainToInstance( CKFinderConfig, plainConfig );

        await validateOrReject( this._config );
    }

```

Now, you can configure your adapter. You need to set `source.type` to the name of the folder where your adapter is created, and set a configiguration compatible with `ExampleConfig` in `source.options`.

```
{
    "source": {
        "type": "example",
        "options": {
            "foo": "bar"
        }
    },
    "ckbox": {
        ...
    }
}

```

To build the application, use the following command:

```
npm run build:adapters

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--verify-connection">

### Verify connection

Verify connection is a step used to check if the migrator can establish the connection to the source storage. You can make a request to any endpoint in your source system to check if authorization passes.

```
import fetch, { Response } from 'node-fetch';

export default class ExampleAdapter implements ISourceStorageAdapter {

        // ...

        const { serviceOrigin } = this._config;

        const response: Response = await fetch( `${ serviceOrigin }/status` );

        if ( !response.ok ) {
            throw new Error( `Failed to connect to the Example service at ${ serviceOrigin }.` );
        }


```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--create-the-migration-plan">

### Create the migration plan

Before the migration starts, the adapter should return the migration plan, the structure containing the list of categories, folders and assets to create.

You should request list of all resources from the source storage and map to the following format.

```
export interface IMigrationPlan {
    readonly categories: ISourceCategory[];
    readonly assets: ISourceAsset[];
}

```

The migration plan should be returned by the `prepareMigrationPlan` of the migrator:

```
import crypto from 'node:crypto';

export default class ExampleAdapter implements ISourceStorageAdapter {

    // ...

    public async prepareMigrationPlan(): Promise<IMigrationPlan> {
        const categoryId: string = crypto.randomUUID();

        return [
            categories: [{
                id: categoryId,
                name: 'Example category',
                allowedExtensions: ['txt'],
                folders: []
            }],
            assets: [{
                id: crypto.randomUUID(),
                name: 'File',
                extension: 'txt',
                location: { categoryId }
                downloadUrl: 'http://localhost/file.txt'
                downloadUrlToReplace: 'http://localhost/file.txt'
            }]
        ];
    }

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--categories-and-folders">

#### Categories and folders

Each category should have unique identifier (it does not matter if it is generated by the source system or using a random ID generator in the adapter), the name, the list of allowed extensions (remember that it should cover at least extensions that will be uploaded to this category) and the folders tree.

```
export interface ISourceCategory {
    readonly id: string;
    readonly name: string;
    readonly allowedExtensions: string[];
    readonly folders: ISourceFolder[];
}

```

If your source system has a similar concept to categories (like “resource types” in CKFinder), you can map them directly to categories. If your system is much like a filesystem, you can treat categories as a top level folders.

To create the folders tree, you need to assign folders to the `folders` property in the category. Each folder should have its own identifier that is unique in the category (for example, a path to the folder or a randomly generated ID), the scope and the name. Folders can contain child folders.

```
export interface ISourceFolder
    readonly id: string;
    readonly name: string;
    readonly childFolders: ISourceFolder[];
}

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--assets">

### Assets

Each category should have:

* Unique identifier - it may be a path to the file or randomly generated ID, same as with folders.
* File name.
* File extension.
* Location (id of the category and optionally id of the folder).
* URL that the migrator should use to download the file.
* URL that is used in your system and should be replaced with a new URL after migration. It may be the same as the URL used for download, but it does not need to. For example, `downloadUrl` may point to the API in the company network and `downloadUrlToReplace` to a publicly available endpoint.

```
export interface ISourceAsset {
    readonly id: string;
    readonly name: string;
    readonly extension: string;
    readonly location: ISourceLocation;
    readonly downloadUrl: string;
    readonly downloadUrlToReplace: string;
}

export interface ISourceLocation {
    readonly categoryId: string;
    readonly folderId?: string;
}

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--migrating-assets">

### Migrating assets

When the migration plan is ready, the migrator knows what categories, folders and assets should be created, but it does not know the files content yet. To provide the file content, you need to return the file stream from `getAsset()` method:

```
import fetch, { Response } from 'node-fetch';

export default class ExampleAdapter implements ISourceStorageAdapter {

    // ...

    public async getAsset( downloadUrl: string ): Promise<IGetAssetResult> {
        const response: Response = await fetch( downloadUrl );

        if ( !response.ok ) {
            throw new Error(
                `Failed to fetch file from the Example service at ${ downloadUrl }. ` +
                `Status code: ${ response.status }. ${ await response.text() }`
            );
        }

        return {
            stream: response.body,
            responsiveImages: []
        }
    }

```

<a id="ckbox/latest/guides/migration/migration-from-custom-sources.html--responsive-images">

#### Responsive images

If your source system provided URLs for [responsive images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia%5Fand%5Fembedding/Responsive%5Fimages), it’s worth to return URLs of the responsive versions in the `responsiveImages` property of `IGetAssetResult`. Thanks to this, the migrator can add the links to the list of URLs mappings.

```
import fetch, { Response } from 'node-fetch';

export default class ExampleAdapter implements ISourceStorageAdapter {

    // ...

    public async getAsset( downloadUrl: string ): Promise<IGetAssetResult> {
        const response: Response = await fetch( downloadUrl );

        if ( !response.ok ) {
            throw new Error(
                `Failed to fetch file from the Example service at ${ downloadUrl }. ` +
                `Status code: ${ response.status }. ${ await response.text() }`
            );
        }

        return {
            stream: response.body,
            responsiveImages: [
                {
                    width: 100,
                    url: `${ downloadUrl }/w_100`
                },
                {
                    width: 300,
                    url: `${ downloadUrl }/w_300`
                }
                // ...
            ]
        }
    }

```

<a id="ckbox/latest/guides/monitoring/insights-panel.html">source file: "ckbox/latest/guides/monitoring/insights-panel.html"</a>

## Insights panel

<a id="ckbox/latest/guides/monitoring/insights-panel.html--insights-panel-overview">

### Insights Panel – overview

The Insights Panel feature allows to gather, list and filter business (audit) logs that come from the CKBox Server. These logs provide a good insight into what is going on internally in your environments. Also, the Insights Panel serves as a useful debugging tool, especially during integration with the CKBox.

<a id="ckbox/latest/guides/monitoring/insights-panel.html--activating-the-insights-feature">

### Activating the Insights feature

By default, the Insights feature is turned off for all environments.

To activate the Insights feature, follow the steps below.

Log in to the Customer Portal and go to the Feature configuration tab for the selected environment. Note that the feature is activated separately for every environment.

Under the INSIGHTS section, switch on the Business logs toggle at the very bottom.

After turning on the toggle, the server will start collecting business and details logs for that environment from now on.

<a id="ckbox/latest/guides/monitoring/insights-panel.html--listing-logs">

### Listing logs

To list the collected logs, go to the Insights Panel tab in the Cloud Services Dashboard (or in the Management Panel if you are using the On-Premises version). By default, the log list displays the business and the details logs from the last 5 minutes. To change the time range, use the date picker to set the desired filtering range.

<a id="ckbox/latest/guides/monitoring/insights-panel.html--filtering-logs">

### Filtering logs

To search the logs, you can use filters to narrow down the desired results.

The currently available filters are:

* `Trace ID` – filtering by `traceId`.
* `User ID` – filtering by `userId`,
* `Error level` – filtering by `warn`, `fail` and `error` levels,
* `Document ID` – filtering by `documentId` – only for the CKEditor Collaboration Services,
* `Asset ID` – filtering by `assetId` – only for the CKBox,
* `Category ID` – filtering by `categoryId` – only for the CKBox,

Filters can be combined with one another.

You can paste the filter value into the filter box (useful for searching by `trace`). It is also possible to choose one of the suggested values – these are aggregated from the logs matching your queries.

<a id="ckbox/latest/guides/monitoring/insights-panel.html--log-structure">

#### Log structure

Here are the key fields included in a log:

* `msg` – A detailed log message.
* `traceId` – A unique RPC call ID.
* `data` – An object containing additional information. It may vary between different logs.
* `time` – An occurrence date.
* `tags` – Tags associated with the log. The possible tags are `business` (information about the main action initiated by the user or an API) or `details` (detailed information about the main action or information about additional events that have been triggered by the main action).
* `status` – The result of a logged action.

An example log:

```
{
    "msg": "The user uploaded a new asset (userId: xhb1jjs10uq8un9wt0vc)",
    "traceId": "b36f1967-7778-4c0d-97a2-37caba24d59e",
    "data": {
      "assetId": "vem71503nieel8ewoxjb",
      "environmentId": "ciy6g1w4y1a6qm146our",
      "folderId": "f5qt-UIwHFqq",
      "userId": "xhb1jjs10uq8un9wt0vc",
      "originalFileName": "spreadsheet.xlsx",
      "mimeType": "application/octet-stream"
    },
    "time": "2023-02-07T09:53:01.257Z",
    "tags": "business",
    "status": "success"
}

```

Log stream records are grouped together and can contain both the `business` and `details` logs linked together by `traceId`. Log details are available after clicking on the log record.

<a id="ckbox/latest/guides/monitoring/insights-panel.html--log-retention">

### Log retention

All logs older than 14 days are periodically removed from the environment. This is done automatically and does not require additional configuration.

<a id="ckbox/latest/guides/on-premises.html">source file: "ckbox/latest/guides/on-premises.html"</a>

## On-premises

The On-Premises version of CKBox is an application that can be installed and run on the customer’s in-house servers and computing infrastructure, including a private cloud. It contains all the features of the CKBox file management platform available in the SaaS version.

Please refer to the [CKBox On-premises Documentation](#cs/latest/onpremises/ckbox-onpremises/overview.html) to read about the system requirements, configuration and supported data storages.

If you wish to purchase a commercial CKBox license, [contact us](https://ckeditor.com/contact/?sales=true#contact-form) to receive an offer tailored to your needs.

<a id="ckbox/latest/guides/quick-start.html">source file: "ckbox/latest/guides/quick-start.html"</a>

## Quick start

In this guide, you will find the quickest and easiest way to run ready-to-use CKBox application. Please refer to [Integrations section](#ckbox/latest/guides/integrations/frameworks/other.html) to check how CKBox can be integrated using `npm` with popular JavaScript frameworks.

<a id="ckbox/latest/guides/quick-start.html--cdn">

### CDN

Using a build served from the CDN is the simplest and fastest way of embedding CKBox in your application. Additionally, all the scripts served from the CDN are loaded faster, as they are hosted on multiple servers around the globe, shortening the response time.

To start using CKBox on your website, embed the following `<script>` tag in the HTML of the page:

```
<script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>

```

Quick implementation example:

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
    </head>
    <body>
        <div id="ckbox"></div>
        <script>
            // You must provide a valid token URL in order to use the application
            // After registering to CKBox, the fastest way to try out CKBox is to use the development token endpoint:
            // https://ckeditor.com/docs/ckbox/latest/guides/configuration/authentication.html#token-endpoint
            CKBox.mount(document.getElementById('ckbox'), {
                tokenUrl: 'https://your.token.url'
            });
        </script>
    </body>
</html>

```

<a id="ckbox/latest/guides/quick-start.html--integration-with-ckeditor">

### Integration with CKEditor

The code snippet below presents the simplest scenario of integration of CKEditor and CKBox. To read more about the integration, please refer to the [CKEditor integration](#ckbox/latest/guides/configuration/ckeditor-integration.html) guide.

```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.umd.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.11.1/ckbox.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/48.0.0/ckeditor5.css" />
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.11.1/styles/themes/lark.css">
    </head>
    <body>
        <div id="editor"></div>

        <script>
            const {
                ClassicEditor,
                Essentials,
                CKBox,
                CKBoxImageEdit,
                PictureEditing,
                ImageUpload,
                Heading,
                Bold,
                Italic,
                BlockQuote,
                Indent,
                Link,
                List
            } = CKEDITOR;

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
                    plugins: [
                        ClassicEditor,
                        CKBox,
                        Bold,
                        CloudServices,
                        Essentials,
                        Font,
                        Image,
                        ImageUploadEditing,
                        ImageUploadProgress,
                        Italic,
                        LinkEditing,
                        Paragraph,
                        PictureEditing
                    ],
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'lark'
                    },
                    toolbar: [
                        'ckbox', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

```

The sample below presents the result of the integration. Try pasting images from clipboard directly into the editing area as well as dropping images — the files will be saved on the fly by CKBox.

You can use the toolbar button to open the CKBox dialog window. There you can manage your files or choose an asset that should be added to the edited content. The image embedded in the editor this way will produce a highly optimized `<picture>` tag. If the image has a description set in its properties in CKBox, the description will be automatically used as an `alt` attribute of the image embedded in the editor.

<a id="ckbox/latest/guides/system-requirements.html">source file: "ckbox/latest/guides/system-requirements.html"</a>

## System requirements

<a id="ckbox/latest/guides/system-requirements.html--browser-compatibility">

### Browser compatibility

CKBox is compatible with the two latest major versions of all modern desktop browsers.

* Chrome
* Firefox
* Edge
* Safari

<a id="ckbox/latest/guides/system-requirements.html--localization">

### Localization

CKBox offers support for a [wide range of languages](#ckbox/latest/guides/configuration/localization.html--list-of-supported-languages). Support for RTL languages will appear in future versions of CKBox.

<a id="ckbox/latest/index.html">source file: "ckbox/latest/index.html"</a>

## CKBox documentation

Welcome to the **CKBox Documentation**. CKBox is a management platform service with a backend-agnostic architecture, availability for both cloud and on-premises, as well as support for over 40 languages, CKBox is compatible with all setups and software platforms. It takes care of file uploads and reduces the effort required on your part to build a complete modern editing solution with support for responsive, optimized images.

With CKBox, you can effortlessly:

* Organize your assets into customizable categories and tags.
* Create, rename, and delete folders.
* Search files and filter results by numerous file properties.
* Easily access recently used files.
* View your images in a high-resolution full-page preview.
* Define alternative text for images and reuse it forever.

To find out more about CKBox, the brand-new file manager, visit the [CKBox website](https://ckeditor.com/ckbox/).

This site will provide you with all the necessary information about:

* [Getting started with CKBox](#ckbox/latest/guides/index.html) – Setting up your copy of CKBox, configuring it, and integrating it with CKEditor 5 and popular frameworks.
* [CKBox features](#ckbox/latest/features/index.html) – Using and administrating CKBox file manager on a daily basis.
* [Examples](#ckbox/latest/examples/index.html) – Various live implementations and customizations examples of CKBox.
* [Support](#ckbox/latest/support/index.html) – Getting support and troubleshooting.

Use the top bar navigation to browse the documentation sections.

<a id="ckbox/latest/support/index.html">source file: "ckbox/latest/support/index.html"</a>

## CKBox Support and feedback

Please contact us at support@cksource.com to:

* Report issues.
* Submit feature requests.
* Suggest improvements in the documentation.

Please check the [Troubleshooting](#ckbox/latest/support/troubleshooting.html) guide first. An answer may be at hand.

<a id="ckbox/latest/support/license.html">source file: "ckbox/latest/support/license.html"</a>

## CKBox License

**[CKBox](https://ckeditor.com/ckbox/)**  
Copyright © 2003-2025, [CKSource Holding sp. z o.o.](https://cksource.com/) All rights reserved.  
CKBox is licensed under a commercial license and is protected by copyright law. For more details about available licensing options please contact us at sales@cksource.com.

**Trademarks**  
CKBox is a trademark of [CKSource Holding sp. z o.o.](https://cksource.com/) All other brand and product names are trademarks, registered trademarks, or service marks of their respective holders.

<a id="ckbox/latest/support/troubleshooting.html">source file: "ckbox/latest/support/troubleshooting.html"</a>

## Troubleshooting

At certain stages of CKBox application integration, some problems and issues may arise.  
This section seeks to address common application issues and integration obstacles.

<a id="ckbox/latest/support/troubleshooting.html--the-token-url-is-missing">

### The token URL is missing

CKBox displays the error message: `Token URL is missing.`

This problem can occur when the token endpoint URL has not been provided for CKBox configuration. CKBox uses JWT tokens for authentication, it is mandatory to supply a valid token endpoint URL for CKBox to work properly.  
[Read more on how to configure CKBox](#ckbox/latest/guides/configuration/configuration-options.html)

<a id="ckbox/latest/support/troubleshooting.html--invalid-jwt-response-from-the-token-endpoint">

### Invalid JWT response from the token endpoint

CKBox displays the error message: `Failed to fetch token. Perhaps provided token URL is unreachable.`

This problem can occur if the token URL does not respond with the valid JWT token. The URL provided may indeed respond correctly, but its response is not a valid JWT token used by CKBox to authenticate users.  
The token endpoint is where the CKBox makes a request to get the token. It should return the token only if the user proves their identity.  
[Read more on how to configure the token URL.](#ckbox/latest/guides/configuration/configuration-options.html--tokenurl)

<a id="ckbox/latest/support/troubleshooting.html--invalid-jwt-returned-from-the-token-callback">

### Invalid JWT returned from the token callback

CKBox displays the error message: `Unable to retrieve a token from the callback.`

This problem can occur if callback provided to `tokenUrl` does not respond with the valid JWT token. It is mandatory to provide a token callback that returns valid JWT tokens for CKBox to work properly.  
[Read more on how to configure the token URL.](#ckbox/latest/guides/configuration/configuration-options.html--tokenurl)

<a id="ckbox/latest/support/troubleshooting.html--invalid-token-payload">

### Invalid token payload

CKBox displays one of the following messages:

* `Invalid JWT token. Field 'aud' is missing.`
* `Invalid JWT token. Field 'sub' is missing.`
* `Invalid JWT token. Field 'iat' is missing.`
* `Invalid JWT token. Field 'auth.ckbox.role' is missing.`

This problem can occur when the token payload is missing one of the information required by CKBox to function correctly.  
[Read more on how to generate a valid JWT token.](#ckbox/latest/guides/configuration/authentication.html--token-payload)

<a id="ckbox/latest/support/troubleshooting.html--malformed-token-url">

### Malformed token URL

CKBox displays the error message: `Token URL seems incorrect.`

This indicates that the supplied token URL is malformed, and is not a valid URL. The token URL should be supplied as part of the CKBox configuration.  
[Read more on how to start with the CKBox](#ckbox/latest/guides/quick-start.html)  
The token endpoint is unreachable

CKBox displays the error message: `Failed to fetch token. Response code: 500.` Such an error indicates that the token endpoint configured in the [tokenUrl](#ckbox/latest/guides/configuration/configuration-options.html--tokenurl) has stopped responding correctly. This could mean a temporary downtime on that endpoint or a more serious server error.

<a id="ckbox/latest/support/troubleshooting.html--malformed-serviceorigin-url">

### Malformed serviceOrigin URL

CKBox displays the error message: `Malformed serviceOrigin URL.`

This problem can occur if the service URL passed to the configuration is not a valid URL. This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.  
[Read more on how to configure CKBox integration.](#ckbox/latest/guides/configuration/configuration-options.html--serviceorigin)

# CKFinder

<a id="ckfinder/latest/index.html">source file: "ckfinder/latest/index.html"</a>

[Home](../../index.html)/[CKFinder](#ckfinder/latest/index.html)

## CKFinder

Use links below to learn more about CKFinder.

<a id="ckfinder/latest/index.html--ckfinder-3">

### [#](#ckfinder/latest/index.html--ckfinder-3)CKFinder 3

[CKFinder 3 Examples](../demo/ckfinder3/samples/)

Examples showcasing various features of CKFinder 3.

[CKFinder 3 Developer’s Guide](../ckfinder3/)

Learn how to run, configure and integrate CKFinder 3 with your website, as well as how to create JavaScript plugins for CKFinder.

[CKFinder 3 - PHP Connector](../ckfinder3-php/)

Learn how to enable and configure the PHP server-side connector as well as create PHP plugins for CKFinder.

[CKFinder 3 - ASP.NET Connector](../ckfinder3-net/)

Learn how to enable and configure the ASP.NET server-side connector as well as create ASP.NET plugins for CKFinder.

[CKFinder 3 - Java Connector](../ckfinder3-java/)

Learn how to enable and configure the Java server-side connector as well as create Java plugins for CKFinder.

<a id="ckfinder/latest/index.html--ckfinder-2">

### [#](#ckfinder/latest/index.html--ckfinder-2)CKFinder 2

If you are using PHP or ASP.NET we recommend using CKFinder 3.

[CKFinder 2 Developer’s Guide](https://docs-old.ckeditor.com/CKFinder%5F2.x/Developers%5FGuide)

Learn how to run, configure and integrate CKFinder 2 with your website, as well as how to create plugins.

[CKFinder 2 User’s Guide](https://docs-old.ckeditor.com/CKFinder%5F2.x/Users%5FGuide)

The User’s Guide contains information about CKFinder 2 intended for end-users. It describes all features and options available in the application and shows how to use it to upload, browse, and manage your media collections.

[CKFinder 2 JavaScript API Documentation](https://docs-old.ckeditor.com/ckfinder%5F2.x%5Fapi/)

API reference for CKFinder 2.

# Trial

<a id="trial/latest/index.html">source file: "trial/latest/index.html"</a>

## CKEditor 5 Premium Features free trial

The CKEditor Premium Features free trial allows you to test the services and plugins available on a subscription at no cost for 14 days. The bundle includes some premium features for CKEditor 5 and it allows you to enable and manage all subscriptions in one place without the need to activate them one by one.

The trial versions of all the features retain the full functionality and act just like the real thing, allowing you to thoroughly assess the premium features’ capabilities when integrated with your software. You can test both the cloud and npm versions of CKEditor 5 Premium features.

Your trial account will be automatically transferred into a GPL account at the end of the trial period. You can also turn it into one of the commercial plans.

<a id="trial/latest/index.html--available-trial-services-and-plugins">

### Available trial services and plugins

At present, the CKEditor Premium Features bundle consists of:

<a id="trial/latest/index.html--saas-features">

#### SaaS features

* [Real-time collaboration](#ckeditor5/latest/features/collaboration/real-time-collaboration/real-time-collaboration.html)
* [CKBox](#ckbox/latest/guides/index.html)
* [Export to PDF](#cs/latest/guides/export-to-pdf/overview.html)
* [Export to Word](#cs/latest/guides/export-to-word/overview.html)
* [Import from Word](#cs/latest/guides/import-from-word/overview.html)

<a id="trial/latest/index.html--standaloneoffline-plugins">

#### Standalone/offline plugins

* Asynchronous collaboration features, including:  
  * [Track changes](#ckeditor5/latest/features/collaboration/track-changes/track-changes.html)
  * [Comments](#ckeditor5/latest/features/collaboration/comments/comments.html)
  * [Revision history](#ckeditor5/latest/features/collaboration/revision-history/revision-history.html)
* [CKEditor AI](#ckeditor5/latest/features/ai/ckeditor-ai-overview.html)
* [Case change](#ckeditor5/latest/features/case-change.html)
* [Document outline](#ckeditor5/latest/features/document-outline.html)
* [Email Configuration Helper](#ckeditor5/latest/features/email-editing/email-configuration-helper.html)
* [Enhanced source code editing](#ckeditor5/latest/features/source-editing/source-editing-enhanced.html)
* [Export with Inline Styles](#ckeditor5/latest/features/export-with-inline-styles.html)
* [Format painter](#ckeditor5/latest/features/format-painter.html)
* [Line height](#ckeditor5/latest/features/line-height.html)
* [Merge fields](#ckeditor5/latest/features/merge-fields.html)
* [Multi-level list](#ckeditor5/latest/features/lists/multi-level-lists.html)
* [Pagination](#ckeditor5/latest/features/pagination/pagination.html)
* [Paste from Office enhanced](#ckeditor5/latest/features/pasting/paste-from-office-enhanced.html)
* [Slash commands](#ckeditor5/latest/features/slash-commands.html)
* [Table of contents](#ckeditor5/latest/features/table-of-contents.html)
* [Templates](#ckeditor5/latest/features/template.html)

<a id="trial/latest/index.html--more-premium-features-to-try">

### More premium features to try

We offer even more premium features for CKEditor 5 that you should also check out. These are not included in this bundle but can also be tested at no cost.

* **[MathType](https://ckeditor.com/mathtype/)** – Makes writing complex mathematical and chemical formulas easy in [CKEditor 5](#ckeditor5/latest/features/math-equations.html).
* **[Spellchecker](https://ckeditor.com/spellchecker/)** – Grammar and spell checking on-the-go, including SCAYT (Spell Check As You Type) as well as distraction-free proofreading for [CKEditor 5](#ckeditor5/latest/features/spelling-and-grammar-checking.html).
* **[CKFinder](https://ckeditor.com/ckfinder/)** – A powerful and easy-to-use Ajax file manager for web browsers that allows you to upload, manage and edit your images in [CKEditor 5](#ckeditor5/latest/features/file-management/ckfinder.html).